{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent Data Platform API",
    "version": "2026-07-01",
    "description": "Trusted, machine-readable datasets for AI agents. Dataset 1: video generation cost estimation across providers, normalized to USD, with provenance (source_url), freshness (verified_at), and confidence on every row. Schema is date-versioned; breaking changes bump meta.schema_version.",
    "contact": { "email": "702executivellc@gmail.com" }
  },
  "servers": [{ "url": "https://agent-data-platform.onrender.com" }],
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/": {
      "get": {
        "summary": "Self-describing index",
        "security": [],
        "responses": { "200": { "description": "Service description, endpoint list, auth instructions." } }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Liveness + database status",
        "security": [],
        "responses": { "200": { "description": "{ ok, db }" } }
      }
    },
    "/v1/keys/signup": {
      "post": {
        "summary": "Self-serve free API key",
        "description": "No auth required. IP rate-limited (3/day). Returns the raw key ONCE; only a hash is stored. Free tier: 100 calls/month.",
        "security": [],
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 100 } } } } }
        },
        "responses": {
          "200": { "description": "Envelope with { api_key, tier, note }. Store the key immediately." },
          "429": { "description": "Signup limit reached for this IP." }
        }
      }
    },
    "/v1/providers": {
      "get": {
        "summary": "List covered providers",
        "responses": { "200": { "description": "Envelope with providers and active model counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/v1/pricing": {
      "get": {
        "summary": "Raw pricing rows with provenance",
        "parameters": [
          { "name": "provider", "in": "query", "schema": { "type": "string" }, "description": "Filter by provider slug" },
          { "name": "model", "in": "query", "schema": { "type": "string" }, "description": "Filter by model slug" }
        ],
        "responses": { "200": { "description": "Envelope with pricing rows. Every row carries source_url, verified_at, and data_confidence (high|medium|low, source reliability set at entry).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }
      }
    },
    "/v1/estimate": {
      "post": {
        "summary": "Cost estimates for a video generation spec, cheapest first",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" } } }
        },
        "responses": {
          "200": { "description": "Envelope with estimates[] sorted by total_usd.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateResponse" } } } },
          "400": { "description": "Invalid spec." },
          "401": { "description": "Missing/invalid API key." },
          "429": { "description": "Rate limit or monthly quota exceeded." }
        }
      }
    },
    "/v1/changes": {
      "get": {
        "summary": "Append-only change log",
        "parameters": [{ "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601; defaults to last 30 days" }],
        "responses": { "200": { "description": "Envelope with change entries, newest first (max 500)." } }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP endpoint (Streamable HTTP, stateless, POST only)",
        "description": "Model Context Protocol server exposing tools: estimate_video_cost, compare_providers, get_pricing_changes. Authenticate with the same X-API-Key header; MCP calls meter identically to REST. Send Accept: application/json, text/event-stream.",
        "responses": { "200": { "description": "JSON-RPC 2.0 response." } }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "data": { "description": "Payload" },
          "meta": {
            "type": "object",
            "properties": {
              "schema_version": { "type": "string", "description": "Date-based; bumps on breaking changes" },
              "generated_at": { "type": "string", "format": "date-time" },
              "source": { "type": "string" }
            }
          }
        }
      },
      "EstimateRequest": {
        "type": "object",
        "required": ["duration_seconds"],
        "properties": {
          "duration_seconds": { "type": "number", "exclusiveMinimum": 0, "maximum": 3600 },
          "count": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 1 },
          "resolution": { "type": "string", "examples": ["720p", "1080p", "4k"] },
          "mode": { "type": "string", "enum": ["text-to-video", "image-to-video"] },
          "require_audio": { "type": "boolean", "default": false }
        }
      },
      "EstimateResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "spec": { "type": "object" },
              "estimates": { "type": "array", "items": { "$ref": "#/components/schemas/Estimate" } },
              "not_directly_estimable": { "type": "array", "items": { "type": "object" }, "description": "Subscription-only rows excluded from per-job ranking" }
            }
          },
          "meta": { "type": "object" }
        }
      },
      "Estimate": {
        "type": "object",
        "properties": {
          "provider": { "type": "string" },
          "model": { "type": "string" },
          "model_name": { "type": "string" },
          "pricing_unit": { "type": "string", "enum": ["per_second", "per_generation", "per_credit"] },
          "per_job_usd": { "type": "number" },
          "total_usd": { "type": "number" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"], "description": "Combined: MIN(data_confidence, freshness/unit-derived). Trust this one." },
          "data_confidence": { "type": "string", "enum": ["high", "medium", "low"], "description": "Source reliability recorded at data entry" },
          "notes": { "type": "array", "items": { "type": "string" } },
          "tier_notes": { "type": "string" },
          "source_url": { "type": "string", "description": "Provenance: where this number came from" },
          "verified_at": { "type": "string", "format": "date-time" },
          "verified_days_ago": { "type": "integer" }
        }
      }
    }
  }
}