REST API

Base URL: https://api.spritefetch.dev. JSON over HTTPS, GET and HEAD only. Full machine spec: openapi.json. Every response carries X-Request-Id.

GET /v1/search

Param	Meaning
`q`	Plain-words query, up to 200 chars. Omit to list newest first.
`mode`	`hybrid` (default; keyword + semantic fused with RRF), `keyword`, `semantic`
`type`	sprite_sheet, tileset, static, ui (comma-separated = OR)
`category`	characters, tilesets, items, ui, effects (explosions, projectiles, spell VFX), structures (towers, bases, buildings)
`style` / `perspective`	pixel-art, hand-drawn, flat / side, top-down, isometric, front
`frame_width`, `frame_height`	Exact pixel size of a frame or tile
`animated`, `animation`	`true`/`false`; an animation name such as `run`
`license_spdx`, `commercial_use`	`CC0-1.0`; `true`
`source`, `pack`	Source id or collection; pack id or slug
`limit`, `cursor`	1–50 (default 20); opaque `next_cursor` from the previous page (expires after 24 h)
`include=pending`	Maintainer keys only (403 otherwise)

Filters apply before ranking. When nothing matches, suggestions lists filters to drop. If the embedder is down, hybrid falls back to keyword with "degraded": true; semantic returns 503.

Assets

GET /v1/assets/{id}/v/{version}/: the record (schema). ?metadata_revision=r returns an earlier revision.
GET /v1/assets/{id}/latest/: 302 to the newest servable version.
GET /v1/assets/{id}/v/{version}/index.md (also /assets/{id}/v/{version}/index.md): markdown for agents.
GET /v1/assets/{id}/v/{version}/download: 302 to the file URL.
Pending assets return 404; rejected ones return 410 with a tombstone asset object.

Files

/files/{id}/v/{version}/{filename}, plus thumb-{sha8}.png, license.txt, and source-terms.txt. Not counted against limits. Immutable caching, ETag = sha256, X-Checksum-SHA256, Repr-Digest, Range requests, HEAD.

Packs

GET /v1/packs: all packs.
GET /v1/packs/{id_or_slug}?version=n&limit=&cursor=: each pack version pins exact asset versions. license_mode is uniform only when every member shares one license.

Machine endpoints

/llms.txt · /openapi.json · /catalog.json (id, version, sha256, file_url for every public file) · /schemas/asset.v1.json

Rate limits (planning defaults)

Caller	Per minute	Per day (UTC)
Anonymous, per IP (IPv6 per /64)	30	500
Free key	60	2,000

Headers: X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute, X-RateLimit-Limit-Day, X-RateLimit-Remaining-Day, X-RateLimit-Reset-Day; 429 adds Retry-After. A present but invalid Authorization header is always 401; it never falls back to anonymous.