{
  "openapi": "3.1.0",
  "info": {
    "title": "Own the Snake public API",
    "version": "1.0.0",
    "summary": "Public sponsor listings, categories and aggregate audience activity.",
    "description": "Discover brands and current audience figures. Terms: https://ownthesnake.com/terms. Privacy: https://ownthesnake.com/privacy."
  },
  "servers": [
    { "url": "https://ownthesnake.com", "description": "Production" }
  ],
  "paths": {
    "/api/stats": { "get": { "summary": "Rolling 24-hour audience", "operationId": "getStats", "responses": { "200": { "description": "Estimated unique browsers, foreground minutes and current human/bot counts, with asOf timestamp" } } } },
    "/api/activity": { "get": { "summary": "Recent anonymous game activity", "operationId": "getActivity", "responses": { "200": { "description": "Recent actual events (join, crown, takedown, new browser, sponsor contribution) with timestamps and bot labels" } } } },
    "/api/bids": { "get": { "summary": "Credited contributions and today's ranking", "operationId": "getBids", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer" }, "description": "Skip this many of the newest contributions" } ], "responses": { "200": { "description": "Newest contributions (3 per page), the total count, and brands ranked by what they paid today" } } } },
    "/api/daily": { "get": { "summary": "Today's best human runs", "operationId": "getDaily", "responses": { "200": { "description": "Top runs since midnight UTC, run and browser counts, and the current crown sponsor" } } } },
    "/api/brandmark": { "get": { "summary": "Brand mark for a player project", "operationId": "getBrandmark", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "A domain (fastdrop.dev) or an X handle (@stackway24)" } ], "responses": { "200": { "description": "PNG or JPEG favicon / avatar, cached for a day" }, "404": { "description": "Nothing resolvable for that value" } } } },
    "/api/categories": { "get": { "summary": "Top three sponsors per category", "operationId": "getCategories", "responses": { "200": { "description": "Categories with ranked sponsor listings" } } } },
    "/api/sponsors": {
      "get": {
        "summary": "Sponsor board",
        "operationId": "listSponsors",
        "parameters": [
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0 }
          }
        ],
        "responses": {
          "200": { "description": "Ranked listings plus audience counters" }
        }
      }
    },
    "/api/sponsors/active": {
      "get": {
        "summary": "Current crown brand",
        "operationId": "getActiveSponsor",
        "responses": {
          "200": {
            "description": "Crown owner, or { campaignId: null } when the board is empty (client then shows the FastDrop house placement)"
          }
        }
      }
    },
    "/api/sponsors/{id}": {
      "get": {
        "summary": "One sponsor plus metrics",
        "operationId": "getSponsor",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Listing and measured clicks / crown time" },
          "404": { "description": "Unknown or hidden listing" }
        }
      }
    },
    "/api/go/{campaignId}": {
      "get": {
        "summary": "Outbound sponsor redirect",
        "operationId": "goSponsor",
        "parameters": [
          {
            "name": "campaignId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "302": { "description": "Redirect to the brand destination" },
          "404": { "description": "Unknown listing" }
        }
      }
    }
  }
}