Introduction

Welcome to the WuwaAPI documentation. This API provides data for characters, weapons, and more from Wuthering Waves.

Base URL: https://wuwa-api.projektcode.com

All endpoints (except health check) are prefixed with /v1.

Rate Limits & Caching

Rate limits are enforced per IP address (defaults shown below).

Type	Limit
List Endpoints	15 requests / min
Detail Endpoints	60 requests / min
Images	60 requests / min
Docs (Swagger UI)	120 requests / min

Self-hosting: configure via RATE_LIMIT_LIST_MAX, RATE_LIMIT_DETAIL_MAX, RATE_LIMIT_IMAGE_MAX, and RATE_LIMIT_DOCS_MAX, and RATE_LIMIT_WINDOW.

Recommendation: keep a separate (higher) limit for /docs so humans browsing Swagger don't compete with API consumers.

Caching

Responses include ETag headers. Please respect Cache-Control directives:

JSON Data: public, max-age=300 (5 minutes)
Images: public, max-age=31536000, immutable (1 year)

Metadata

GET /healthz

Health check endpoint. Returns 200 OK if service is up.

GET /v1/meta

Get server metadata and version info.

Characters

GET /v1/characters

List all characters with pagination and filtering.

Query Parameters

Param	Description
search	Filter by name (fuzzy match)
element	Filter by element (e.g. Glacio)
weaponType	Filter by weapon type
rarity	Filter by star rating (4 or 5)
limit	Max results (default 50)
offset	Pagination offset

GET /v1/characters/:id

Get detailed info for a single character.

:id can be the character name (case-insensitive, e.g. jinhsi).

{
  "name": "Jinhsi",
  "rarity": 5,
  "element": "Spectro",
  "weaponType": "Broadblade",
  "stats": { ... },
  "images": { ... }
}

Images

GET /v1/characters/:id/images

List available image files for a character.

curl "https://wuwa-api.projektcode.com/v1/characters/jinhsi/images"

The response includes URLs like /v1/characters/jinhsi/images/icon.webp.

GET /v1/characters/:id/images/:file

Serve a raw image file.

:file must match one of the filenames returned by /v1/characters/:id/images (including extension, e.g. icon.webp).

These responses are immutable and cached for 1 year.

GET /v1/images/characters/:id/:asset.webp

Static image URLs referenced by the JSON payloads (e.g. icon.webp, card.webp, splash.webp, attribute.webp).

curl -I "https://wuwa-api.projektcode.com/v1/images/characters/jinhsi/icon.webp"

Weapons

GET /v1/weapons

List all weapons.

Query Parameters

Param	Description
search	Filter by name
type	Filter by weapon type (e.g. Sword)
rarity	Filter by star rating
limit	Max results
offset	Pagination offset

GET /v1/weapons/:id

Get detailed info for a single weapon.