{
  "openapi": "3.1.0",
  "info": {
    "title": "TokenBinge Model Prices API",
    "version": "1.4.0",
    "description": "Current and dated AI API tariffs. First-party prices take priority and clearly labelled OpenRouter tariffs fill otherwise-unpriced models. A TokenBinge account and a price-only API key are required."
  },
  "servers": [{ "url": "https://tokenbinge.com" }],
  "paths": {
    "/api/v1/prices": {
      "get": {
        "summary": "List model prices",
        "description": "Returns models with a usable tariff from the latest fully verified snapshot. history=1 returns dated price changes and their source.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "provider", "in": "query", "schema": { "type": "string", "maxLength": 80 }, "description": "Exact lowercase catalogue provider." },
          { "name": "model", "in": "query", "schema": { "type": "string", "maxLength": 160 }, "description": "Normalized model-name prefix." },
          { "name": "history", "in": "query", "schema": { "type": "string", "enum": ["1"] }, "description": "Return dated price-category periods with the previous amount, change, billing unit, source kind and pricing proof URL." },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string", "maxLength": 512 }, "description": "Opaque cursor returned by the previous page." }
        ],
        "responses": {
          "200": {
            "description": "A bounded page of prices. The account-wide allowance is 10 requests per minute and 500 per UTC day.",
            "headers": {
              "RateLimit-Limit": { "schema": { "type": "string" } },
              "RateLimit-Remaining": { "schema": { "type": "integer" } },
              "RateLimit-Reset": { "schema": { "type": "integer" } },
              "X-RateLimit-Daily-Remaining": { "schema": { "type": "integer" } },
              "X-RateLimit-Daily-Reset": { "schema": { "type": "integer" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PricePage" } } }
          },
          "400": { "description": "Invalid filter or cursor." },
          "401": { "description": "Missing, malformed, unknown, or revoked TokenBinge price API key." },
          "429": { "description": "Account quota exceeded. Retry-After gives the wait in seconds." },
          "503": { "description": "The completed price catalogue is temporarily unavailable." }
        }
      },
      "options": {
        "summary": "CORS preflight",
        "responses": { "204": { "description": "Preflight accepted." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "TokenBinge price API key" }
    },
    "schemas": {
      "PriceModel": {
        "type": "object",
        "required": ["model", "provider", "input", "cachedInput", "cacheWrite5m", "cacheWrite1h", "output", "unitPrice", "pricingUrl", "known", "confidence"],
        "properties": {
          "model": { "type": "string" },
          "provider": { "type": "string" },
          "catalogueProvider": { "type": "string" },
          "providerAssumed": { "type": "boolean", "const": true },
          "input": { "type": ["number", "null"] },
          "cachedInput": { "type": ["number", "null"] },
          "cacheWrite5m": { "type": ["number", "null"] },
          "cacheWrite1h": { "type": ["number", "null"] },
          "output": { "type": ["number", "null"] },
          "unitPrice": {
            "type": ["object", "null"],
            "description": "Price for one generated item when this model is not billed by token.",
            "properties": {
              "priceUsd": { "type": "number" },
              "unit": { "type": "string", "enum": ["song", "clip_30_seconds"] },
              "pricingUrl": { "type": "string", "format": "uri" }
            },
            "required": ["priceUsd", "unit", "pricingUrl"]
          },
          "pricingUrl": { "type": ["string", "null"], "format": "uri", "description": "Provider or model pricing page used as evidence." },
          "modelUrl": { "type": ["string", "null"], "format": "uri", "description": "Provider or OpenRouter model page used as evidence." },
          "providerUrl": { "type": ["string", "null"], "format": "uri" },
          "priceSource": { "type": "string", "enum": ["official", "openrouter"] },
          "availability": { "type": "string", "const": "available" },
          "known": { "type": "object", "additionalProperties": { "type": "boolean" } },
          "confidence": { "type": "string" },
          "sources": { "type": ["object", "null"], "additionalProperties": true }
        }
      },
      "PricePeriod": {
        "type": "object",
        "required": ["model", "provider", "category", "usdPerMillion", "previousUsdPerMillion", "changeUsdPerMillion", "priceUsd", "previousPriceUsd", "changePriceUsd", "changePercent", "priceUnit", "pricingUrl", "validFrom", "validTo", "sources"],
        "properties": {
          "model": { "type": "string" },
          "provider": { "type": "string" },
          "category": { "type": "string", "enum": ["input", "cached_input", "cache_write_5m", "cache_write_1h", "output", "unit_price"] },
          "usdPerMillion": { "type": ["number", "null"] },
          "previousUsdPerMillion": { "type": ["number", "null"], "description": "Null for the first observed price or after an unavailable period." },
          "changeUsdPerMillion": { "type": ["number", "null"] },
          "priceUsd": { "type": "number", "description": "Price expressed in USD for priceUnit." },
          "previousPriceUsd": { "type": ["number", "null"] },
          "changePriceUsd": { "type": ["number", "null"] },
          "changePercent": { "type": ["number", "null"] },
          "priceUnit": { "type": "string", "enum": ["million_tokens", "song", "clip_30_seconds"] },
          "pricingUrl": { "type": ["string", "null"], "format": "uri" },
          "priceSource": { "type": "string", "enum": ["official", "openrouter", "unavailable"] },
          "validFrom": { "type": "string", "format": "date-time" },
          "validTo": { "type": ["string", "null"], "format": "date-time" },
          "sourceId": { "type": "string" },
          "confidence": { "type": "string" },
          "sources": { "type": ["object", "null"], "description": "Price provenance and descriptive metadata.", "additionalProperties": true }
        }
      },
      "PricePage": {
        "type": "object",
        "required": ["updatedAt", "verifiedAt", "count", "unit", "sourcePolicy", "historyAvailableFrom", "nextCursor"],
        "properties": {
          "updatedAt": { "type": "string", "format": "date-time", "description": "Time at which the latest changed price snapshot became effective." },
          "verifiedAt": { "type": "string", "format": "date-time", "description": "Most recent completed daily refresh, including applicable first-party verification and OpenRouter collection." },
          "count": { "type": "integer" },
          "total": { "type": "integer" },
          "totalModels": { "type": "integer" },
          "unit": { "type": "string", "const": "USD per million tokens", "description": "Default unit for token-priced fields. Individual models can additionally expose unitPrice." },
          "sourcePolicy": { "type": "string", "const": "official_then_openrouter" },
          "historyAvailableFrom": { "type": "string", "format": "date" },
          "note": { "type": "string" },
          "models": { "type": "array", "items": { "$ref": "#/components/schemas/PriceModel" } },
          "periods": { "type": "array", "items": { "$ref": "#/components/schemas/PricePeriod" } },
          "nextCursor": { "type": ["string", "null"] }
        }
      }
    }
  }
}