{
  "openapi": "3.1.0",
  "info": {
    "title": "TensorFeed.ai API",
    "description": "Real-time AI news, model pricing, service status, and machine-payable premium intelligence for AI agents. Free tier requires no auth. Premium tier is pay-per-call in USDC on Base mainnet (no accounts, no API keys, no Stripe). Discovery manifest at /.well-known/x402.\n\nOperated by Pizza Robot Studios LLC, California, USA.",
    "version": "2026.04.27",
    "contact": {
      "name": "TensorFeed support",
      "email": "evan@tensorfeed.ai",
      "url": "https://tensorfeed.ai/developers/agent-payments"
    },
    "license": { "name": "Inference-only, no training", "url": "https://tensorfeed.ai/terms" }
  },
  "servers": [
    { "url": "https://tensorfeed.ai/api", "description": "Production" }
  ],
  "tags": [
    { "name": "Free", "description": "No auth required. Open for AI agents and humans." },
    { "name": "Payment", "description": "Buy credits, confirm USDC transactions, check balance and usage. Public flow." },
    { "name": "Premium", "description": "Pay-per-call in USDC on Base. 1 credit per call (~$0.02). Bearer token via /api/payment/buy-credits." }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "tf_live_<256-bit hex>",
        "description": "TensorFeed bearer token. Obtained via POST /api/payment/buy-credits + POST /api/payment/confirm. Each premium API call decrements credits."
      }
    }
  },
  "security": [],
  "paths": {
    "/news": {
      "get": {
        "tags": ["Free"],
        "summary": "Latest AI news articles",
        "description": "Aggregated from 15+ RSS sources. Updated every 10 minutes.",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }
        ]
      }
    },
    "/status": {
      "get": {
        "tags": ["Free"],
        "summary": "Real-time AI service status",
        "description": "Operational status of major AI APIs (Claude, OpenAI, Gemini, Mistral, Cohere, Replicate, HuggingFace, Perplexity, Midjourney). Polled every 5 minutes."
      }
    },
    "/models": {
      "get": {
        "tags": ["Free"],
        "summary": "AI model pricing and specs",
        "description": "Per-model input/output prices, context windows, capabilities, tiers."
      }
    },
    "/benchmarks": {
      "get": {
        "tags": ["Free"],
        "summary": "AI model benchmark scores",
        "description": "Scores across SWE-bench, MMLU-Pro, GPQA-Diamond, MATH, HumanEval, and others."
      }
    },
    "/history": {
      "get": {
        "tags": ["Free"],
        "summary": "Available daily history snapshot dates",
        "description": "Lists dates with snapshots and the snapshot types available (pricing, models, benchmarks, status, agent-activity)."
      }
    },
    "/history/{date}/{type}": {
      "get": {
        "tags": ["Free"],
        "summary": "Read a specific historical snapshot",
        "parameters": [
          { "name": "date", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } },
          { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": ["pricing", "models", "benchmarks", "status", "agent-activity"] } }
        ]
      }
    },
    "/preview/routing": {
      "get": {
        "tags": ["Free"],
        "summary": "Free routing preview (top-1 model, rate-limited)",
        "description": "5 calls per UTC day per IP. The paid /api/premium/routing has no rate limit and returns top-N with full breakdown.",
        "parameters": [
          { "name": "task", "in": "query", "schema": { "type": "string", "enum": ["code", "reasoning", "creative", "general"] } },
          { "name": "budget", "in": "query", "schema": { "type": "number" } },
          { "name": "min_quality", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1 } }
        ]
      }
    },
    "/payment/info": {
      "get": {
        "tags": ["Payment"],
        "summary": "Wallet, pricing tiers, supported flows, verification metadata",
        "description": "Cross-check the wallet address before sending funds. Includes operator (Pizza Robot Studios LLC, California, USA), wallet (USDC on Base), pricing (50 credits per $1 USDC, volume discounts at $5/$30/$200), both flows (credits and x402 fallback), and trust attestation."
      }
    },
    "/payment/buy-credits": {
      "post": {
        "tags": ["Payment"],
        "summary": "Quote a credit purchase (30-min TTL)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["amount_usd"],
                "properties": {
                  "amount_usd": { "type": "number", "minimum": 0.5, "maximum": 10000 }
                }
              }
            }
          }
        }
      }
    },
    "/payment/confirm": {
      "post": {
        "tags": ["Payment"],
        "summary": "Verify USDC tx on-chain and mint a bearer token",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["tx_hash"],
                "properties": {
                  "tx_hash": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" },
                  "nonce": { "type": "string", "description": "Optional memo from buy-credits to apply volume discount" }
                }
              }
            }
          }
        }
      }
    },
    "/payment/balance": {
      "get": {
        "tags": ["Payment"],
        "summary": "Check remaining credits for the current bearer token",
        "security": [{ "bearerAuth": [] }]
      }
    },
    "/payment/usage": {
      "get": {
        "tags": ["Payment"],
        "summary": "Per-token call history (last 100 calls aggregated by endpoint)",
        "security": [{ "bearerAuth": [] }]
      }
    },
    "/premium/routing": {
      "get": {
        "tags": ["Premium"],
        "summary": "Top-N ranked model recommendations with composite score",
        "description": "1 credit. Synthesizes live pricing, benchmarks, and provider status into a ranked list.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "task", "in": "query", "schema": { "type": "string", "enum": ["code", "reasoning", "creative", "general"] } },
          { "name": "budget", "in": "query", "schema": { "type": "number" } },
          { "name": "min_quality", "in": "query", "schema": { "type": "number", "minimum": 0, "maximum": 1 } },
          { "name": "top_n", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10 } }
        ]
      }
    },
    "/premium/whats-new": {
      "get": {
        "tags": ["Premium"],
        "summary": "Agent morning brief",
        "description": "1 credit. Pricing changes, new/removed models, status incidents, top news headlines from last 1-7 days.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 7 } },
          { "name": "news_limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 25 } }
        ]
      }
    },
    "/premium/news/search": {
      "get": {
        "tags": ["Premium"],
        "summary": "Full-text news search",
        "description": "1 credit. Relevance-scored search over the article corpus with date/provider/category filters.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "provider", "in": "query", "schema": { "type": "string" } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }
        ]
      }
    },
    "/premium/history/pricing/series": {
      "get": {
        "tags": ["Premium"],
        "summary": "Daily price points for one model with min/max/delta",
        "description": "1 credit. Range capped at 90 days, default 30 days back.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ]
      }
    },
    "/premium/history/benchmarks/series": {
      "get": {
        "tags": ["Premium"],
        "summary": "Score evolution for one benchmark on one model",
        "description": "1 credit.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "benchmark", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ]
      }
    },
    "/premium/history/status/uptime": {
      "get": {
        "tags": ["Premium"],
        "summary": "Daily uptime rollup for one provider",
        "description": "1 credit. Operational/degraded/down day counts plus uptime % (degraded = half-credit).",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "provider", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }
        ]
      }
    },
    "/premium/history/compare": {
      "get": {
        "tags": ["Premium"],
        "summary": "Diff two daily snapshots",
        "description": "1 credit. Returns added, removed, and changed entries with deltas.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["pricing", "benchmarks"] } }
        ]
      }
    },
    "/premium/cost/projection": {
      "get": {
        "tags": ["Premium"],
        "summary": "Project workload cost across 1-10 models",
        "description": "1 credit. Daily/weekly/monthly/yearly totals plus cheapest-monthly ranking.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated list of 1-10 models" },
          { "name": "input_tokens_per_day", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0 } },
          { "name": "output_tokens_per_day", "in": "query", "required": true, "schema": { "type": "number", "minimum": 0 } },
          { "name": "horizon", "in": "query", "schema": { "type": "string", "enum": ["daily", "weekly", "monthly", "yearly"] } }
        ]
      }
    },
    "/premium/forecast": {
      "get": {
        "tags": ["Premium"],
        "summary": "Linear-regression forecast for a price field or benchmark",
        "description": "1 credit. 95% prediction interval and confidence label so agents can ignore low-signal forecasts.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "target", "in": "query", "required": true, "schema": { "type": "string", "enum": ["price", "benchmark"] } },
          { "name": "model", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "field", "in": "query", "schema": { "type": "string", "enum": ["inputPrice", "outputPrice", "blended"] } },
          { "name": "benchmark", "in": "query", "schema": { "type": "string" } },
          { "name": "lookback", "in": "query", "schema": { "type": "integer", "minimum": 7, "maximum": 90 } },
          { "name": "horizon", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30 } }
        ]
      }
    },
    "/premium/providers/{name}": {
      "get": {
        "tags": ["Premium"],
        "summary": "Provider deep-dive in one paid call",
        "description": "1 credit. Live status + components, all models with pricing + tier + benchmarks joined, recent news, agent traffic.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } }
        ]
      }
    },
    "/premium/compare/models": {
      "get": {
        "tags": ["Premium"],
        "summary": "Side-by-side comparison of 2-5 AI models",
        "description": "1 credit. Pricing, benchmarks (normalized), status, news. Plus rankings.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "ids", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma-separated list of 2-5 model ids/names" }
        ]
      }
    },
    "/premium/agents/directory": {
      "get": {
        "tags": ["Premium"],
        "summary": "Enriched AI agents directory",
        "description": "1 credit. Catalog joined with status, news, traffic, flagship pricing, and a 0-100 trending score.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["operational", "degraded", "down", "unknown"] } },
          { "name": "open_source", "in": "query", "schema": { "type": "boolean" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["trending", "alphabetical", "status", "price_low", "price_high", "news_count"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }
        ]
      }
    },
    "/premium/watches": {
      "post": {
        "tags": ["Premium"],
        "summary": "Register a webhook watch (price, status, or digest)",
        "description": "1 credit per registration. HMAC-SHA256 signed POST delivery. 90-day TTL, default fire cap 100, per-token cap 25.",
        "security": [{ "bearerAuth": [] }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["spec", "callback_url"],
                "properties": {
                  "spec": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "type": { "const": "price" },
                          "model": { "type": "string" },
                          "field": { "type": "string", "enum": ["inputPrice", "outputPrice", "blended"] },
                          "op": { "type": "string", "enum": ["lt", "gt", "changes"] },
                          "threshold": { "type": "number" }
                        },
                        "required": ["type", "model", "field", "op"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": { "const": "status" },
                          "provider": { "type": "string" },
                          "op": { "type": "string", "enum": ["becomes", "changes"] },
                          "value": { "type": "string", "enum": ["operational", "degraded", "down"] }
                        },
                        "required": ["type", "provider", "op"]
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": { "const": "digest" },
                          "cadence": { "type": "string", "enum": ["daily", "weekly"] }
                        },
                        "required": ["type", "cadence"]
                      }
                    ]
                  },
                  "callback_url": { "type": "string", "format": "uri" },
                  "secret": { "type": "string" },
                  "fire_cap": { "type": "integer", "minimum": 1, "maximum": 1000 }
                }
              }
            }
          }
        }
      },
      "get": {
        "tags": ["Premium"],
        "summary": "List active watches owned by the current bearer token",
        "description": "Free for the owning bearer token (no credits charged).",
        "security": [{ "bearerAuth": [] }]
      }
    },
    "/premium/watches/{id}": {
      "get": {
        "tags": ["Premium"],
        "summary": "Read one watch (must be owned by the current token)",
        "description": "Free.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wat_[a-f0-9]{24}$" } }
        ]
      },
      "delete": {
        "tags": ["Premium"],
        "summary": "Delete an owned watch",
        "description": "Free.",
        "security": [{ "bearerAuth": [] }],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wat_[a-f0-9]{24}$" } }
        ]
      }
    }
  },
  "externalDocs": {
    "description": "Full agent payments documentation",
    "url": "https://tensorfeed.ai/developers/agent-payments"
  }
}