{
  "openapi": "3.1.0",
  "info": {
    "title": "Racerverse Public and Agent API",
    "version": "2026-07-16",
    "description": "Public Racerverse catalog, media, feed, sitemap, and agent-discovery endpoints. Canonical art identity is DNA/artUuid-based; tokenId and dnaIndex are ownership metadata, not art addresses.",
    "contact": {
      "name": "Racerverse support",
      "email": "hello@racerverse.com",
      "url": "https://racerverse.com/docs/api"
    }
  },
  "servers": [
    { "url": "https://racerverse.com", "description": "Production" }
  ],
  "externalDocs": {
    "description": "Human-readable API documentation",
    "url": "https://racerverse.com/docs/api"
  },
  "paths": {
    "/api/collection/public": {
      "get": {
        "operationId": "listPublicRacers",
        "summary": "List the public Racerverse collection",
        "description": "Returns minted and preview racers. Use view=viewer&assetsOnly=1 for the compact canonical-art contract. Requests from the Racerverse site/viewer are trusted; other browser origins can use a Racerverse API key.",
        "security": [{ "bearerAuth": [] }, {}],
        "parameters": [
          { "$ref": "#/components/parameters/Page" },
          { "$ref": "#/components/parameters/Limit" },
          { "name": "filter", "in": "query", "schema": { "type": "string", "default": "all" }, "description": "Compatibility filter used by viewer clients." },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["all", "minted", "preview"], "default": "all" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["newest", "oldest", "name-asc", "name-desc"], "default": "newest" } },
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search plate, public identity, and trait values." },
          { "name": "trait", "in": "query", "schema": { "type": "string" }, "description": "Exact trait-value filter." },
          { "name": "view", "in": "query", "schema": { "type": "string", "enum": ["full", "viewer"], "default": "full" } },
          { "name": "assetsOnly", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Accepts 1 or true; excludes rows without published canonical assets." }
        ],
        "responses": {
          "200": {
            "description": "Paginated racers",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/RacerCollection" }
              }
            }
          },
          "401": { "description": "API key required for an untrusted browser origin" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/og/racer": {
      "get": {
        "operationId": "getRacerShareImage",
        "summary": "Get a racer share image",
        "parameters": [
          { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Plate slug or DNA public key." }
        ],
        "responses": {
          "200": { "description": "1200 by 630 PNG", "content": { "image/png": { "schema": { "type": "string", "contentEncoding": "binary" } } } },
          "404": { "description": "Racer not found" }
        }
      }
    },
    "/.well-known/x402-discovery": {
      "get": {
        "operationId": "discoverX402Purchases",
        "summary": "Discover the agent-only x402 purchase rail",
        "responses": {
          "200": { "description": "Current networks, pricing URL, endpoints, request contract, and payment flow", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }
        }
      }
    },
    "/api/x402/status": {
      "get": {
        "operationId": "getX402Status",
        "summary": "Check whether the agent purchase rail is ready",
        "responses": {
          "200": { "description": "Rail status", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "503": { "description": "Purchase upstream is not configured" }
        }
      }
    },
    "/api/x402/pricing": {
      "get": {
        "operationId": "getX402Pricing",
        "summary": "Get current x402 pricing and supported quantities",
        "responses": {
          "200": { "description": "Current x402 tiers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "503": { "description": "Purchase upstream is not configured" }
        }
      }
    },
    "/api/rss": {
      "get": {
        "operationId": "getDevlogFeed",
        "summary": "Get the Racerverse devlog RSS feed",
        "responses": { "200": { "description": "RSS XML", "content": { "application/rss+xml": { "schema": { "type": "string" } } } } }
      }
    },
    "/api/sitemap-racers.xml": {
      "get": {
        "operationId": "getRacerSitemap",
        "summary": "Get racer detail URLs and locale alternates",
        "responses": { "200": { "description": "XML sitemap", "content": { "application/xml": { "schema": { "type": "string" } } } } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "rk_ API key",
        "description": "Create and manage keys at /account/api-keys."
      }
    },
    "parameters": {
      "Page": { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } },
      "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 48 } }
    },
    "schemas": {
      "RacerCollection": {
        "type": "object",
        "required": ["racers", "total", "page", "limit", "totalPages"],
        "properties": {
          "racers": { "type": "array", "items": { "$ref": "#/components/schemas/Racer" } },
          "total": { "type": "integer" },
          "page": { "type": "integer" },
          "limit": { "type": "integer" },
          "totalPages": { "type": "integer" },
          "sort": { "type": "string" },
          "view": { "type": "string" },
          "filter": { "type": "object", "additionalProperties": true }
        }
      },
      "Racer": {
        "type": "object",
        "properties": {
          "publicKey": { "type": "string", "pattern": "^dna-", "description": "Canonical public identity: dna-<artUuid>." },
          "racerKey": { "type": "string", "pattern": "^dna-" },
          "displayId": { "type": "string", "description": "Human-readable license plate." },
          "plateSlug": { "type": "string" },
          "status": { "type": "string", "enum": ["minted", "preview"] },
          "dna": { "type": ["string", "null"] },
          "dnaIndex": { "type": ["integer", "string", "null"], "description": "Ownership/catalog metadata; never use as canonical art identity." },
          "artUuid": { "type": "string", "format": "uuid" },
          "canonicalAssetBase": { "type": "string", "format": "uri", "description": "https://cdn.racerverse.com/art/dna/<artUuid>" },
          "canonicalGlb": { "type": "string", "format": "uri", "description": "Canonical high-quality model_1k.glb URL." },
          "canonicalHero": { "type": "string", "format": "uri", "description": "Canonical hero_alpha.png URL." },
          "glbUrl": { "type": "string", "format": "uri" },
          "imageUrl": { "type": "string", "format": "uri", "description": "Preferred hero_alpha_2048.webp URL." },
          "assetReady": { "type": "boolean" },
          "traits": { "type": "object", "additionalProperties": true }
        }
      }
    }
  }
}