openapi: 3.1.0
info:
  title: TensorFeed API
  version: 1.0.0
  summary: Real-time AI ecosystem data for humans and agents
  description: |
    TensorFeed.ai is a free, no-auth JSON API for AI news, service status, model pricing, GPU pricing, agent directories, and AFTA (Agent Fair-Trade Agreement) data, plus a paid premium tier (USDC on Base, x402 compatible) for ranked model routing, search, history series, watches, and computed intelligence.

    Highlights for AI agents:
    - No API key on free endpoints. CORS enabled. Rate limit 120 req/min/IP.
    - AFTA-certified: code-enforced no-charge on 5xx, circuit breaker, schema failure, or stale data. Every paid response carries an Ed25519-signed receipt.
    - Premium tier accepts pay-per-call USDC on Base, no accounts, no traditional processors.
    - Machine-readable manifests at /.well-known/agent-fair-trade.json and /llms.txt.

    Full endpoint catalog at /api/meta. Standard at https://tensorfeed.ai/agent-fair-trade.

  x-guidance: |
    For agents discovering this API: most endpoints are free and require no auth. Hit /api/meta to see every endpoint with parameters. The MCP server `@tensorfeed/mcp-server` exposes 42 tools (8 free, 14 premium); install with `npx -y @tensorfeed/mcp-server`. Premium endpoints under /api/premium/* cost 1-3 credits each ($0.02 each at base rate, USDC on Base mainnet). Buy a bearer token via POST /api/payment/buy-credits + /api/payment/confirm, OR pay per call via x402 by retrying with X-Payment-Tx header. Every paid call returns an Ed25519-signed receipt verifiable at /api/receipt/verify. AFTA-certified: no charge on 5xx, breaker, schema failure, or stale data; standard at /.well-known/agent-fair-trade.json.
  termsOfService: https://tensorfeed.ai/terms
  contact:
    name: TensorFeed Support
    email: contact@tensorfeed.ai
    url: https://tensorfeed.ai/developers
  license:
    name: API content licensed for inference-only use
    url: https://tensorfeed.ai/agent-fair-trade
  x-logo:
    url: https://tensorfeed.ai/tensorfeed-logo.png
    altText: TensorFeed.ai

servers:
  - url: https://tensorfeed.ai
    description: Production

security: []

tags:
  - name: Discovery
    description: Service metadata, health, and the canonical endpoint catalog.
  - name: News
    description: AI news aggregated from all major sources.
  - name: Status
    description: Real-time operational status for major AI services.
  - name: Models
    description: Model specs, pricing, and benchmarks.
  - name: Agents
    description: Agent directory and live agent traffic on TensorFeed itself.
  - name: GPU
    description: GPU rental marketplace pricing.
  - name: MCP
    description: Model Context Protocol registry telemetry.
  - name: History
    description: Daily snapshots for time-series analysis.
  - name: Probe
    description: Active LLM endpoint latency probes.
  - name: AFTA
    description: 'Agent Fair-Trade Agreement: standard, adopters, receipts.'
  - name: Payment
    description: x402-compatible USDC-on-Base credit purchase + balance.
  - name: Premium
    description: Pay-per-call computed intelligence (requires bearer token).

paths:
  /api/meta:
    get:
      tags: [Discovery]
      summary: Canonical endpoint catalog and self-description
      operationId: getMeta
      security: []
      description: |
        The authoritative listing of every public endpoint, including AFTA self-description, freshness SLAs, rate limits, chaos-engineering headers, and the supportive-sites network. The first thing an agent should read.
      responses:
        '200':
          description: Site metadata and full endpoint catalog
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, site: { type: string }, api: { type: object } } }

  /api/health:
    get:
      tags: [Discovery]
      summary: Service health and freshness summary
      operationId: getHealth
      security: []
      responses:
        '200':
          description: Counts and last-updated timestamps for every data subsystem
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  timestamp: { type: string, format: date-time }
                  news: { type: object }
                  models: { type: object }
                  benchmarks: { type: object }
                  agents: { type: object }

  /api/news:
    get:
      tags: [News]
      summary: Aggregated AI news articles
      operationId: getNews
      security: []
      parameters:
        - in: query
          name: category
          schema: { type: string, example: OpenAI }
          description: Filter by source category (OpenAI, Anthropic, Google, etc.)
        - in: query
          name: limit
          schema: { type: integer, default: 50, minimum: 1, maximum: 200 }
      responses:
        '200':
          description: Recent articles, snippets clipped to ~200 chars, prompt-injection sanitized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  count: { type: integer }
                  articles:
                    type: array
                    items: { $ref: '#/components/schemas/NewsArticle' }
                  sanitization: { type: string, example: enabled }

  /api/agents/news:
    get:
      tags: [News, Agents]
      summary: Agent-friendly compact news payload
      operationId: getAgentsNews
      security: []
      description: Lighter article payload tuned for LLM context windows. Same source data as /api/news.
      responses:
        '200':
          description: Compact news objects.
          content:
            application/json:
              schema: { type: object }

  /api/feed.xml:
    get:
      tags: [News]
      summary: RSS 2.0 feed of all AI news
      operationId: getFeedRss
      security: []
      responses:
        '200':
          description: RSS XML
          content:
            application/rss+xml: { schema: { type: string } }

  /api/feed.json:
    get:
      tags: [News]
      summary: JSON Feed 1.1
      operationId: getFeedJson
      security: []
      responses:
        '200':
          description: JSON Feed
          content:
            application/feed+json: { schema: { type: object } }

  /api/status:
    get:
      tags: [Status]
      summary: Operational status for major AI services
      operationId: getStatus
      security: []
      responses:
        '200':
          description: Per-service status with components
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  services:
                    type: array
                    items: { $ref: '#/components/schemas/StatusService' }

  /api/status/summary:
    get:
      tags: [Status]
      summary: Lightweight status counts for dashboards
      operationId: getStatusSummary
      security: []
      responses:
        '200':
          description: Counts of operational, degraded, and down services
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  summary:
                    type: object
                    properties:
                      total: { type: integer }
                      operational: { type: integer }
                      degraded: { type: integer }
                      down: { type: integer }

  /api/models:
    get:
      tags: [Models]
      summary: AI model pricing and specs
      operationId: getModels
      security: []
      description: Input/output cost per 1M tokens, context window, capabilities, across 200+ models from major labs.
      responses:
        '200':
          description: Provider-grouped model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  lastUpdated: { type: string }
                  providers:
                    type: array
                    items: { type: object }

  /api/agents/pricing:
    get:
      tags: [Models]
      summary: Agent-friendly compact pricing payload
      operationId: getAgentsPricing
      security: []
      responses:
        '200':
          description: Compact pricing list
          content:
            application/json:
              schema: { type: object }

  /api/benchmarks:
    get:
      tags: [Models]
      summary: Public benchmark scores for major models
      operationId: getBenchmarks
      security: []
      responses:
        '200':
          description: Benchmark catalog with per-model scores
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, benchmarks: { type: array, items: { type: object } } } }

  /api/agents/directory:
    get:
      tags: [Agents]
      summary: Curated directory of AI agents and frameworks
      operationId: getAgentsDirectory
      security: []
      responses:
        '200':
          description: Categorized directory of production-grade agents.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  source: { type: string }
                  categories: { type: array, items: { type: object } }
                  agents: { type: array, items: { type: object } }

  /api/agents/activity:
    get:
      tags: [Agents]
      summary: Live AI bot traffic on TensorFeed
      operationId: getAgentActivity
      security: []
      description: Last hits per known AI bot user-agent (ClaudeBot, GPTBot, Applebot, etc). Useful for understanding crawler adoption.
      responses:
        '200':
          description: Recent agent hits
          content:
            application/json:
              schema:
                type: object
                properties:
                  today_count: { type: integer }
                  last_updated: { type: string, format: date-time }
                  recent:
                    type: array
                    items:
                      type: object
                      properties:
                        bot: { type: string }
                        endpoint: { type: string }
                        timestamp: { type: string, format: date-time }

  /api/podcasts:
    get:
      tags: [News]
      summary: Recent AI podcast episodes
      operationId: getPodcasts
      security: []
      responses:
        '200':
          description: Episode list with show, title, published date.
          content:
            application/json:
              schema: { type: object }

  /api/trending-repos:
    get:
      tags: [News]
      summary: Trending GitHub repos in AI
      operationId: getTrendingRepos
      security: []
      responses:
        '200':
          description: Top repos by recent star velocity in AI/ML topics.
          content:
            application/json:
              schema: { type: object }

  /api/gpu/pricing:
    get:
      tags: [GPU]
      summary: Current GPU rental pricing snapshot
      operationId: getGpuPricing
      security: []
      responses:
        '200':
          description: Aggregated pricing across cloud GPU marketplaces.
          content:
            application/json:
              schema: { type: object }

  /api/gpu/pricing/cheapest:
    get:
      tags: [GPU]
      summary: Cheapest current offer for a canonical GPU
      operationId: getGpuPricingCheapest
      security: []
      parameters:
        - in: query
          name: gpu
          required: true
          schema: { type: string, example: H100 }
          description: Canonical GPU id (H100, H200, A100-80GB, RTX-4090, etc.)
        - in: query
          name: type
          schema: { type: string, enum: [on_demand, spot], default: on_demand }
      responses:
        '200':
          description: Top 3 cheapest offers right now.
          content:
            application/json:
              schema: { type: object }

  /api/mcp/registry/snapshot:
    get:
      tags: [MCP]
      summary: Daily MCP server registry summary
      operationId: getMcpRegistrySnapshot
      security: []
      description: Today's count + 1-day delta of the official MCP server registry. Refreshed daily.
      responses:
        '200':
          description: Latest registry summary
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, summary: { type: object } } }

  /api/probe/latest:
    get:
      tags: [Probe]
      summary: Last 24h of LLM endpoint latency probes
      operationId: getProbeLatest
      security: []
      description: Active probe results (TTFB, total) per provider. Refreshed every 15 min.
      responses:
        '200':
          description: Probe summary
          content:
            application/json:
              schema: { type: object }

  /api/papers/ai-trending:
    get:
      tags: [Papers]
      summary: Daily citation-ranked AI/ML papers from Semantic Scholar
      operationId: getPapersAITrending
      security: []
      description: Five fan-out queries (LLM, transformer, RLHF, AI agents, diffusion), deduped by paperId, top 30 by citation count. Refreshed daily at 11:00 UTC.
      responses:
        '200':
          description: Curated papers snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/papers/arxiv-recent:
    get:
      tags: [Papers]
      summary: Most recent arXiv submissions (cs.AI / cs.LG / cs.CL / cs.CV)
      operationId: getPapersArxivRecent
      security: []
      description: Top 50 recent submissions by date, deduped by arxivId. Refreshed daily at 11:30 UTC.
      responses:
        '200':
          description: Recent arXiv submissions snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/hf/trending:
    get:
      tags: [Hugging Face]
      summary: Top HF models, datasets, and Spaces
      operationId: getHFTrending
      security: []
      description: Daily snapshot against the public HF API. Models + datasets ranked by downloads (top 30 each); Spaces ranked by likes (top 30). Day-over-day deltas across the dated keys yield a true trending signal once multiple snapshots accumulate. Refreshed daily at 12:00 UTC.
      responses:
        '200':
          description: Top-downloaded models and datasets snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/issues/hot:
    get:
      tags: [GitHub]
      summary: Currently-hot GitHub issues across AI repos
      operationId: getHotIssues
      security: []
      description: Five fan-out keyword-phrase searches ("large language model", "AI agent", transformer, "machine learning", LLM), is:issue is:open comments>=10 updated within the last 7 days, deduped by URL, top 30 by comment count. Refreshed daily at 12:30 UTC. Companion to /api/trending-repos.
      responses:
        '200':
          description: Hot AI issues snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/reddit/trending:
    get:
      tags: [Reddit]
      summary: Currently-hot AI threads on Reddit
      operationId: getRedditTrending
      security: []
      description: Daily snapshot of hot threads from 7 AI-relevant subreddits (LocalLLaMA, MachineLearning, ClaudeAI, OpenAI, singularity, artificial, AI_Agents). Stickied and NSFW posts filtered, deduped by post id, top 30 by score. Titles sanitized at capture time. Refreshed daily at 13:00 UTC. Companion to /api/issues/hot.
      responses:
        '200':
          description: Hot Reddit AI threads snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/today:
    get:
      tags: [Composite]
      summary: AI ecosystem today (composite brief)
      operationId: getToday
      security: []
      description: Single edge-cached endpoint that fans out across every daily TensorFeed feed (news, 3 paper feeds, HF models/datasets/Spaces, hot GitHub issues, Reddit threads, OpenRouter catalog summary, provider status) and returns a structured response. Saves a client from orchestrating 9 separate calls. Optional ?sections=news,papers,hf,community,inference,status and ?limit=1-10 (default 3 items per section).
      parameters:
        - in: query
          name: sections
          schema: { type: string }
          description: Comma-separated subset of sections (news, papers, hf, community, inference, status). Default all six.
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 10 }
          description: Max items per subsection. Default 3, max 10.
      responses:
        '200':
          description: Composite AI ecosystem brief
          content:
            application/json:
              schema: { type: object }

  /api/papers/hf-daily:
    get:
      tags: [Papers]
      summary: HF Daily Papers (editor-curated AI papers with community signal)
      operationId: getPapersHFDaily
      security: []
      description: Hugging Face's editor-curated daily AI/ML papers feed, layered with community upvotes and discussion counts. Different signal from /api/papers/arxiv-recent (firehose) and /api/papers/ai-trending (citation-ranked). Refreshed daily at 14:30 UTC. Titles sanitized at capture time.
      responses:
        '200':
          description: HF Daily Papers snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/openrouter/models:
    get:
      tags: [OpenRouter]
      summary: Cross-provider AI model catalog snapshot
      operationId: getOpenRouterModels
      security: []
      description: Daily snapshot of OpenRouter's normalized cross-provider model catalog. 200+ models across 50+ inference providers with comparable per-token pricing, context window, modality, and provider metadata. Pairs with /api/models (curated frontier-lab catalog) by surfacing the long tail of OSS models on cloud inference. Refreshed daily at 14:00 UTC.
      responses:
        '200':
          description: OpenRouter catalog snapshot
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, snapshot: { type: object } } }

  /api/history:
    get:
      tags: [History]
      summary: Index of historical daily snapshots
      operationId: getHistoryIndex
      security: []
      responses:
        '200':
          description: Available date ranges per snapshot type.
          content:
            application/json:
              schema: { type: object }

  /api/history/{date}/{type}:
    get:
      tags: [History]
      summary: Read one historical snapshot
      operationId: getHistorySnapshot
      security: []
      parameters:
        - in: path
          name: date
          required: true
          schema: { type: string, pattern: '^\d{4}-\d{2}-\d{2}$', example: '2026-05-01' }
        - in: path
          name: type
          required: true
          schema: { type: string, enum: [pricing, benchmarks, status, news, mcp-registry, probe, gpu-pricing] }
      responses:
        '200':
          description: Snapshot payload
          content:
            application/json:
              schema: { type: object }
        '404': { description: Snapshot not found }

  /api/afta/adopters:
    get:
      tags: [AFTA]
      summary: Machine-readable AFTA adopter directory
      operationId: getAftaAdopters
      security: []
      description: Public list of sites that publish a /.well-known/agent-fair-trade.json manifest. Not authoritative; agents should verify each manifest directly.
      responses:
        '200':
          description: Adopter list
          content:
            application/json:
              schema: { type: object }

  /api/model-deprecations:
    get:
      tags: [Catalogs]
      summary: AI model deprecation calendar
      operationId: getModelDeprecations
      security: []
      description: |
        Provider-by-provider registry of model retirements and
        deprecation announcements (OpenAI, Anthropic, Google, Cohere,
        and others). Each entry carries `announcedDate`,
        `deprecationDate`, `sunsetDate`, the recommended replacement
        model id, and a `sourceUrl` pointing at the provider's own
        announcement page. Curated; updated as new deprecations land.
        Edge-cached 600s.
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            type: string
            example: 'OpenAI'
          description: Filter to a single provider (case-insensitive match on the provider field).
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [announced, deprecated, sunsetted]
          description: Filter by lifecycle stage.
      responses:
        '200':
          description: List of model deprecations sorted by most recent activity first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  source: { type: string }
                  lastUpdated: { type: string, format: date }
                  count: { type: integer }
                  deprecations:
                    type: array
                    items:
                      type: object
                      required: [id, provider, model, status, sourceUrl]
                      properties:
                        id: { type: string }
                        provider: { type: string }
                        model: { type: string }
                        modelDisplay: { type: string }
                        status:
                          type: string
                          enum: [announced, deprecated, sunsetted]
                        announcedDate: { type: string, format: date }
                        deprecationDate: { type: string, format: date }
                        sunsetDate: { type: string, format: date }
                        replacement: { type: string }
                        notes: { type: string }
                        sourceUrl: { type: string, format: uri }

  /api/payment/info:
    get:
      tags: [Payment]
      summary: Wallet, pricing, and operator info
      operationId: getPaymentInfo
      security: []
      responses:
        '200':
          description: Payment metadata for buying credits.
          content:
            application/json:
              schema: { type: object }

  /api/payment/buy-credits:
    post:
      tags: [Payment]
      summary: Initiate a credit purchase (sender_wallet binding required)
      description: |
        Issues a 30-minute payment quote bound to the EVM address that
        will sign the on-chain USDC transfer. Required body fields:
        `amount_usd` (0.5 to 10000) and `sender_wallet` (0x-prefixed
        40-char EVM address). The `/api/payment/confirm` endpoint will
        reject any tx whose on-chain `from` does not match the
        sender_wallet bound here, which closes the public-mempool tx
        sniping vector.
      operationId: postBuyCredits
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount_usd, sender_wallet]
              properties:
                amount_usd: { type: number, minimum: 0.5, maximum: 10000, example: 1.0 }
                sender_wallet:
                  type: string
                  pattern: '^0x[a-fA-F0-9]{40}$'
                  example: '0xabcdef0123456789abcdef0123456789abcdef01'
      responses:
        '200':
          description: Quote with credits, instructions to send USDC on Base, and the bound sender_wallet.
          content:
            application/json:
              schema: { type: object }
        '400':
          description: Returned if amount_usd is out of range or sender_wallet is missing/malformed.

  /api/payment/confirm:
    post:
      tags: [Payment]
      summary: Confirm a USDC payment and receive bearer token (nonce required)
      description: |
        Verifies the USDC Transfer event on-chain via Base RPC and
        mints a tf_live_ bearer token tied to the credit balance.
        Both `tx_hash` and `nonce` are required (the legacy no-nonce
        path is closed to prevent public-mempool tx sniping). The
        on-chain sender of the verified tx MUST match the
        sender_wallet bound to the quote at /api/payment/buy-credits;
        a mismatch returns `{ ok: false, error: "sender_mismatch" }`.
      operationId: postPaymentConfirm
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [tx_hash, nonce]
              properties:
                tx_hash:
                  type: string
                  pattern: '^0x[a-fA-F0-9]{64}$'
                  example: '0xabc...'
                nonce:
                  type: string
                  description: The memo returned from /api/payment/buy-credits.
                  example: 'tf-abc123'
      responses:
        '200':
          description: Bearer token + credit balance.
          content:
            application/json:
              schema: { type: object }
        '400':
          description: Possible errors include `nonce_required`, `quote_not_found_or_expired`, `quote_expired`, `sender_mismatch`, `tx_already_claimed`, `verification_failed`.

  /api/payment/balance:
    get:
      tags: [Payment]
      summary: Token balance and usage
      operationId: getPaymentBalance
      security: [{ BearerAuth: [] }]
      responses:
        '200':
          description: Credits remaining, total spent, recent calls.
          content:
            application/json:
              schema: { type: object }

  /api/payment/no-charge-stats:
    get:
      tags: [AFTA, Payment]
      summary: Public no-charge counter (AFTA evidence)
      operationId: getNoChargeStats
      security: []
      description: Aggregate count of paid calls that were waived under AFTA guarantees (5xx, breaker, schema fail, stale data).
      responses:
        '200':
          description: No-charge counter
          content:
            application/json:
              schema: { type: object }

  /api/receipt/verify:
    post:
      tags: [AFTA]
      summary: Verify an Ed25519-signed receipt
      operationId: postReceiptVerify
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [receipt]
              properties:
                receipt: { type: string, description: Receipt blob from a previous paid response }
      responses:
        '200':
          description: Verification result
          content:
            application/json:
              schema: { type: object, properties: { ok: { type: boolean }, valid: { type: boolean }, signed_at: { type: string } } }

  /api/preview/routing:
    get:
      tags: [Premium]
      summary: Public preview of premium model routing
      operationId: getRoutingPreview
      security: []
      description: Free preview of the premium routing endpoint. Returns top-1 recommendation only. Use /api/premium/routing for ranked top-N with full reasoning.
      responses:
        '200':
          description: Recommended model id and one-line rationale.
          content:
            application/json:
              schema: { type: object }

  /api/premium/routing:
    get:
      tags: [Premium]
      summary: Ranked model routing recommendations
      operationId: getPremiumRouting
      security: [{ BearerAuth: [] }]
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: prompt
          schema: { type: string }
        - in: query
          name: optimize
          schema: { type: string, enum: [cost, speed, quality, balanced] }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  description: Free-form task description used to rank candidate models
                optimize:
                  type: string
                  enum: [cost, speed, quality, balanced]
                  description: Ranking objective
      responses:
        '200':
          description: Ranked top-N model recommendations with rationale and signed receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment Required

  /api/premium/news/search:
    get:
      tags: [Premium]
      summary: Full-text search across AI news archive
      operationId: getPremiumNewsSearch
      security: [{ BearerAuth: [] }]
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: q
          required: true
          schema: { type: string }
        - in: query
          name: from
          schema: { type: string, format: date }
        - in: query
          name: to
          schema: { type: string, format: date }
        - in: query
          name: limit
          schema: { type: integer, default: 25, maximum: 100 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [q]
              properties:
                q:
                  type: string
                  description: Search query string
                from:
                  type: string
                  format: date
                  description: Start of date range (inclusive)
                to:
                  type: string
                  format: date
                  description: End of date range (inclusive)
                limit:
                  type: integer
                  default: 25
                  maximum: 100
                  description: Max number of articles to return
      responses:
        '200':
          description: Matching articles, ranked.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment Required

  /api/premium/cost/projection:
    get:
      tags: [Premium]
      summary: Compute monthly cost across model candidates
      operationId: getPremiumCostProjection
      security: [{ BearerAuth: [] }]
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: model
          required: true
          schema: { type: string, example: 'opus-4-7,gpt-5-5' }
        - in: query
          name: input_tokens_per_day
          schema: { type: integer }
        - in: query
          name: output_tokens_per_day
          schema: { type: integer }
        - in: query
          name: horizon
          schema: { type: string, enum: [daily, monthly, yearly], default: monthly }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model]
              properties:
                model:
                  type: string
                  description: Comma-separated model ids (1-10), e.g. "opus-4-7,gpt-5-5"
                input_tokens_per_day:
                  type: integer
                  description: Projected daily input token volume
                output_tokens_per_day:
                  type: integer
                  description: Projected daily output token volume
                horizon:
                  type: string
                  enum: [daily, monthly, yearly]
                  default: monthly
                  description: Time horizon for cost summary
      responses:
        '200':
          description: Projected cost per model.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment Required

  /api/premium/whats-new:
    get:
      tags: [Premium]
      summary: Aggregated daily delta across the whole TensorFeed dataset
      operationId: getPremiumWhatsNew
      security: [{ BearerAuth: [] }]
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: days
          schema: { type: integer, default: 1, minimum: 1, maximum: 7 }
        - in: query
          name: news_limit
          schema: { type: integer, default: 10, maximum: 50 }
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                days:
                  type: integer
                  default: 1
                  minimum: 1
                  maximum: 7
                  description: Lookback window in days
                news_limit:
                  type: integer
                  default: 10
                  maximum: 50
                  description: Max number of news headlines included
      responses:
        '200':
          description: New models, new pricing, new status incidents, top news.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment Required

  /api/premium/route-verdict:
    get:
      tags: [Premium]
      summary: Single best model to use right now (signed routing decision)
      operationId: getPremiumRouteVerdict
      security: [{ BearerAuth: [] }]
      description: "The signed model-routing decision. For ?task=code|reasoning|creative|general or ?model=<id-or-name>, returns the single best model to use right now, fusing pricing, contamination-discounted benchmark capability, real production usage, measured p95 latency probes, and live incident-triage operational state, plus runners-up and an AFTA-signed receipt over the inputs. 30-minute operational freshness SLA, no-charge when the live layer is stale."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: task
          schema: { type: string, enum: [code, reasoning, creative, general] }
        - in: query
          name: model
          schema: { type: string }
        - in: query
          name: max_latency_p95_ms
          schema: { type: number }
        - in: query
          name: require_operational
          schema: { type: boolean }
        - in: query
          name: exclude_deprecated
          schema: { type: boolean }
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

  /api/premium/provider-reliability-verdict:
    get:
      tags: [Premium]
      summary: Most dependable frontier provider to build on right now
      operationId: getPremiumProviderReliabilityVerdict
      security: [{ BearerAuth: [] }]
      description: "Which frontier AI provider is the most dependable to build on right now, and which is the riskiest? Ranks the providers TensorFeed actively probes by measured operational reliability, fusing availability and tail consistency (p50 over p95) from its own latency probes into one dependability score, names the most dependable and the riskiest, and returns the full per-provider ranking with an AFTA-signed receipt. 30-minute freshness SLA, no-charge when stale."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters: []
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

  /api/premium/x402-settlement-verdict:
    get:
      tags: [Premium]
      summary: Ruling on the Base x402 USDC settlement market
      operationId: getPremiumX402SettlementVerdict
      security: [{ BearerAuth: [] }]
      description: "Is the Base x402 USDC settlement market growing, is it concentrated or a real market, and who leads? Rules over TensorFeed's own on-chain settlement index: momentum versus the prior window of equal length, concentration by the Herfindahl index, and the leading publisher, plus the full per-publisher volume ranking. Optional window=24h|7d|30d (default 7d). Coverage is the Base settlements TensorFeed indexes, forward-only from launch. 10-minute freshness SLA, no-charge when stale."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: window
          schema: { type: string, enum: [24h, 7d, 30d], default: 7d }
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

  /api/premium/stack-safety-verdict:
    get:
      tags: [Premium]
      summary: GO/HOLD/BLOCK deploy gate per AI-stack package
      operationId: getPremiumStackSafetyVerdict
      security: [{ BearerAuth: [] }]
      description: "GO / HOLD / BLOCK deploy gate for your AI stack, fusing the ingested AI-CVE batch with CISA KEV. Pass packages=name@version (up to 10)."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: packages
          required: true
          schema: { type: string, example: 'vllm@0.5.0,transformers@4.40.0' }
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

  /api/premium/benchmark-trust-verdict:
    get:
      tags: [Premium]
      summary: Trust band and 0-100 score per AI benchmark
      operationId: getPremiumBenchmarkTrustVerdict
      security: [{ BearerAuth: [] }]
      description: "Is an AI benchmark a trustworthy capability signal, or saturated/contaminated/near-ceiling so a high score should be down-weighted? Trust band + 0-100 score per benchmark."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: benchmark
          schema: { type: string }
        - in: query
          name: category
          schema: { type: string }
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

  /api/premium/failover-verdict:
    get:
      tags: [Premium]
      summary: Best operational failover target when a provider degrades
      operationId: getPremiumFailoverVerdict
      security: [{ BearerAuth: [] }]
      description: "Provider A is degraded, which operational provider do I fail over to for this task right now? Confirms A against live incident triage, then recommends the best operational alternative. Pass ?from=<provider>."
      x-payment-info:
        price:
          mode: fixed
          currency: USD
          amount: "0.02"
        protocols:
          - x402: {}
      parameters:
        - in: query
          name: from
          required: true
          schema: { type: string }
        - in: query
          name: task
          schema: { type: string, enum: [code, reasoning, creative, general] }
      responses:
        '200':
          description: Signed verdict with AFTA receipt.
          content:
            application/json:
              schema: { type: object }
        '402':
          description: Payment required; returns the x402 challenge.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tf_live_*
      description: |
        Bearer token from POST /api/payment/confirm. Required for premium endpoints. Each call decrements credits.
        On insufficient credits, the server returns HTTP 402 Payment Required with a body that points to /api/payment/buy-credits (x402-compatible).

  schemas:
    NewsArticle:
      type: object
      required: [id, title, url]
      properties:
        id: { type: string }
        title: { type: string }
        url: { type: string, format: uri }
        source: { type: string }
        sourceDomain: { type: string }
        snippet: { type: string }
        categories: { type: array, items: { type: string } }
        publishedAt: { type: string, format: date-time }
        fetchedAt: { type: string, format: date-time }

    StatusService:
      type: object
      required: [name, status]
      properties:
        name: { type: string }
        provider: { type: string }
        status: { type: string, enum: [operational, degraded, partial_outage, major_outage, maintenance, unknown] }
        components:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              status: { type: string }
        lastChecked: { type: string, format: date-time }

externalDocs:
  description: Full developer documentation, SDKs, machine-readable manifests, and the daily Hugging Face dataset mirror
  url: https://tensorfeed.ai/developers

x-tensorfeed:
  hugging_face_dataset:
    repo: tensorfeed/ai-ecosystem-daily
    url: https://huggingface.co/datasets/tensorfeed/ai-ecosystem-daily
    description: Daily JSONL snapshots of the entire public API. Inference-only license.
    cadence: daily at 08:00 UTC
