{ "openapi": "3.1.0", "info": { "title": "Spritefetch API", "version": "1.0.0-prototype", "description": "Read-only API for CC0 2D sprite sheets and tilesets. GET and HEAD only. No key needed; an optional `Authorization: Bearer ` raises the limits. Every response has X-Request-Id; CORS * everywhere." }, "servers": [ { "url": "https://api.spritefetch.dev" } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Optional free API key (ssk_...)" } }, "schemas": { "Asset": { "$ref": "https://api.spritefetch.dev/schemas/asset.v1.json" }, "SearchResult": { "$ref": "https://api.spritefetch.dev/schemas/search-result.v1.json" }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "status", "message", "docs_url", "request_id" ], "properties": { "code": { "enum": [ "invalid_parameter", "invalid_cursor", "invalid_api_key", "maintainer_only", "not_found", "method_not_allowed", "gone", "rate_limited", "internal_error", "unavailable" ] }, "status": { "type": "integer" }, "message": { "type": "string" }, "param": { "type": "string" }, "retry_after_s": { "type": "integer" }, "docs_url": { "type": "string" }, "request_id": { "type": "string" } } }, "asset": { "type": "object", "description": "Tombstone (410 only): id, version, name, category, style, verification_status, rejection_reason" } } } } }, "security": [ {}, { "bearer": [] } ], "paths": { "/v1/search": { "get": { "operationId": "search", "summary": "Hybrid keyword + semantic search (RRF k=60). Filters apply before ranking.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "" }, { "name": "mode", "in": "query", "required": false, "schema": { "enum": [ "hybrid", "keyword", "semantic" ], "default": "hybrid" }, "description": "" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma list of: sprite_sheet, tileset, static, ui" }, "description": "" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma list of: characters, tilesets, items, ui, effects, structures" }, "description": "" }, { "name": "license_spdx", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "commercial_use", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "" }, { "name": "frame_width", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "For tilesets matches tile_width" }, { "name": "frame_height", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "For tilesets matches tile_height" }, { "name": "style", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma list of: pixel-art, hand-drawn, flat" }, "description": "" }, { "name": "perspective", "in": "query", "required": false, "schema": { "enum": [ "side", "top-down", "isometric", "front" ] }, "description": "" }, { "name": "animated", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "" }, { "name": "animation", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "pack", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "include", "in": "query", "required": false, "schema": { "enum": [ "pending" ] }, "description": "Maintainer keys only" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Results", "headers": { "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "schema": { "type": "integer" }, "description": "Next 00:00 UTC, epoch seconds" } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object" }, "total": { "type": "integer" }, "total_is_estimate": { "type": "boolean" }, "degraded": { "type": "boolean" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "next_cursor": { "type": [ "string", "null" ] }, "suggestions": { "type": "array", "description": "Only when results is empty. drop_filter items: {type, drop}. One external_generators item: {type, label, message, disclaimer, affiliated: false, cc0: false, generators: [{name, url}]} from config/external-generators.json.", "items": { "type": "object", "properties": { "type": { "type": "string" }, "drop": { "type": "string" } } } } } } } } }, "400": { "description": "invalid_parameter / invalid_cursor", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "maintainer_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/assets/{id}/v/{version}/": { "get": { "operationId": "getAsset", "summary": "Full record for one asset version", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_[a-z0-9]{12}$" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "metadata_revision", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "include", "in": "query", "required": false, "schema": { "enum": [ "pending" ] }, "description": "" } ], "responses": { "200": { "description": "Asset record", "headers": { "ETag": { "schema": { "type": "string" } }, "X-RateLimit-Limit-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Minute": { "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "schema": { "type": "integer" }, "description": "Next 00:00 UTC, epoch seconds" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "gone (tombstone)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/assets/{id}/latest/": { "get": { "operationId": "getLatest", "summary": "302 to the highest publicly servable version", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_[a-z0-9]{12}$" } } ], "responses": { "302": { "description": "Redirect" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/assets/{id}/v/{version}/index.md": { "get": { "operationId": "getMarkdown", "summary": "Markdown page for agents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_[a-z0-9]{12}$" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "Markdown", "content": { "text/markdown": {} } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "# Not available for download" } } } }, "/v1/assets/{id}/v/{version}/download": { "get": { "operationId": "download", "summary": "302 to file_url (REST parity for the MCP download tool)", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_[a-z0-9]{12}$" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "302": { "description": "Redirect to the immutable file" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "gone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/packs": { "get": { "operationId": "listPacks", "summary": "All packs (collections)", "responses": { "200": { "description": "Packs" } } } }, "/v1/packs/{id_or_slug}": { "get": { "operationId": "getPack", "summary": "One pack version with pinned asset versions", "parameters": [ { "name": "id_or_slug", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "description": "" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Pack" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/files/{id}/v/{version}/{filename}": { "get": { "operationId": "file", "summary": "Immutable PNG (also thumb-{sha8}.png, license.txt, source-terms.txt). HEAD and Range supported. Not rate-limited.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^asset_[a-z0-9]{12}$" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "filename", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "File", "headers": { "ETag": { "schema": { "type": "string" } }, "X-Checksum-SHA256": { "schema": { "type": "string" } }, "Repr-Digest": { "schema": { "type": "string" } } }, "content": { "image/png": {} } }, "206": { "description": "Partial content" }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Rejected (plain text)" } } } }, "/catalog.json": { "get": { "operationId": "catalog", "summary": "Every public version: id, version, sha256, file_url", "responses": { "200": { "description": "Catalog" } } } } }, "x-mcp": { "url": "https://api.spritefetch.dev/mcp", "tools": [ "search", "get_asset", "download" ] }, "x-rate-limits": { "anon": { "minute": 30, "day": 500 }, "free": { "minute": 60, "day": 2000 }, "maintainer": { "minute": 600, "day": null } } }