openapi: 3.1.0
info:
  title: apiroute.dev Pricing API
  version: 0.1.0
  description: Machine-readable LLM API pricing snapshot used by apiroute.dev. Data is transformed from LiteLLM pricing metadata; verify provider pages before production routing or purchasing decisions.
servers:
  - url: https://apiroute.dev
paths:
  /api/agent-instructions:
    get:
      operationId: getAgentInstructions
      summary: Get apiroute.dev agent instructions
      description: Returns the stable machine-readable contract for agents using apiroute.dev, including endpoint order, local-vs-cloud flow, neutral recommendation policy, citation guidance, commercial boundaries, and posting rules.
      responses:
        "200":
          description: Agent instructions contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentInstructions"
  /api/live-prices:
    get:
      operationId: getLivePrices
      summary: Get LLM API pricing snapshot
      description: Returns model pricing data with metadata, generated_at, source_url, excluded_models, pricing_status, and provider verification notes. The updater keeps the previous generated_at value when the comparable pricing payload did not change.
      responses:
        "200":
          description: Pricing snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PricingSnapshot"
  /api/models:
    get:
      operationId: getModels
      summary: Get model pricing entries
      responses:
        "200":
          description: Model pricing entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  models:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelPrice"
                required:
                  - models
  /api/providers:
    get:
      operationId: getProviders
      summary: Get providers represented in the pricing snapshot
      responses:
        "200":
          description: Provider list
          content:
            application/json:
              schema:
                type: object
                properties:
                  providers:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        model_count:
                          type: integer
                      required:
                        - name
                        - model_count
                required:
                  - providers
  /api/marketing-radar:
    get:
      operationId: getMarketingRadar
      summary: Get human-approved marketing radar candidates
      description: Returns demand signals from public discussions. All suggested replies require manual review before posting.
      responses:
        "200":
          description: Marketing radar approval queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MarketingRadar"
  /api/operator-inbox:
    get:
      operationId: getOperatorInbox
      summary: Get manual-review operator inbox items
      description: Returns a compact queue derived from the marketing radar for Gravity Control Center style operator review. This endpoint is never an auto-posting feed.
      responses:
        "200":
          description: Operator inbox queue
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OperatorInbox"
  /api/commercial-options:
    get:
      operationId: getCommercialOptions
      summary: Get commercial validation options
      description: Returns machine-readable commercial options for apiroute.dev, including waitlist, premium API interest, sponsorship policy, and explicit non-sale rules.
      responses:
        "200":
          description: Commercial validation options
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CommercialOptions"
  /api/route-recommendation-guide:
    get:
      operationId: getRouteRecommendationGuide
      summary: Get Best Route recommendation guide
      description: Returns the static machine-readable guide for reproducing the homepage's client-side Best Route V1 logic. This is documentation, not a server-side recommendation result.
      responses:
        "200":
          description: Route recommendation guide
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RouteRecommendationGuide"
  /api/recommend-route:
    get:
      operationId: getRecommendRouteContract
      summary: Get Recommend Route contract
      description: Returns the request schema, scoring contract, and example response shape for the live server-side recommendation API.
      responses:
        "200":
          description: Recommend Route contract and examples
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecommendRouteContract"
    post:
      operationId: recommendRoute
      summary: Get a rule-based LLM route recommendation
      description: Returns a server-side rule-based recommendation from task, token count, output need, priority, cache share, and capability requirements. Results are estimates from the current pricing snapshot and provider pages should be verified before production use.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecommendRouteRequest"
            examples:
              codingAgent:
                value:
                  task: Multi-file coding agent loop with tool calls, patch review, and repeated project context.
                  use_case: coding
                  priority: balanced
                  privacy_class: internal
                  prompt_tokens: 32000
                  expected_output_tokens: 4000
                  cache_share: 0.55
                  requirements:
                    function_calling: true
                    prompt_caching: true
                    min_context_window: 36000
                  local_first: true
              ragDocs:
                value:
                  task: RAG over long documents with repeated document prefixes and decision-ready summaries.
                  use_case: rag
                  priority: balanced
                  privacy_class: internal
                  prompt_tokens: 85000
                  expected_output_tokens: 3500
                  cache_share: 0.7
                  requirements:
                    prompt_caching: true
                    min_context_window: 88500
                  local_first: false
              visionTask:
                value:
                  task: Image and document screenshot analysis with structured reasoning output.
                  use_case: vision
                  priority: premium
                  privacy_class: public
                  prompt_tokens: 6000
                  expected_output_tokens: 2500
                  cache_share: 0.1
                  requirements:
                    vision: true
                    min_context_window: 8500
                  local_first: false
              cheapBatch:
                value:
                  task: High-volume text classification, translation, cleanup, or extraction where cost matters most.
                  use_case: translation
                  priority: cheapest
                  privacy_class: public
                  prompt_tokens: 12000
                  expected_output_tokens: 1800
                  cache_share: 0
                  requirements:
                    min_context_window: 13800
                  local_first: false
              localFirstAgent:
                value:
                  task: Local-first personal agent fallback check before selecting a cloud route.
                  use_case: agents
                  priority: cheapest
                  privacy_class: sensitive
                  prompt_tokens: 16000
                  expected_output_tokens: 2500
                  cache_share: 0.25
                  requirements:
                    function_calling: true
                    min_context_window: 18500
                  local_first: true
      responses:
        "200":
          description: Rule-based recommendation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RecommendRouteResponse"
        "400":
          description: Invalid request
        "405":
          description: Method not allowed
  /api/token-waste-check:
    get:
      operationId: getTokenWasteCheckContract
      summary: Get Token Waste Check contract
      description: Returns the machine-readable contract for the homepage Token Waste Check, including status labels, cheaper-route comparison fields, SLM/budget-route policy, worker usage, and manual approval boundaries.
      responses:
        "200":
          description: Token Waste Check contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenWasteCheckContract"
components:
  schemas:
    AgentInstructions:
      type: object
      properties:
        metadata:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
            generated_at:
              type: string
            last_verified:
              type: string
            status:
              type: string
            canonical_url:
              type: string
            human_entry:
              type: string
            contact:
              type: string
          required:
            - name
            - version
            - generated_at
            - status
            - canonical_url
        purpose:
          type: string
        core_principles:
          type: array
          items:
            type: string
        fetch_order:
          type: array
          items:
            type: object
            properties:
              step:
                type: integer
              endpoint:
                type: string
              method:
                type: string
              use:
                type: string
              required:
                type: boolean
            required:
              - step
              - endpoint
              - method
              - use
        stable_endpoints:
          type: object
          additionalProperties:
            type: string
        decision_flow:
          type: object
        recommendation_policy:
          type: object
        commercial_policy:
          type: object
          properties:
            ranking_influenced_by_affiliate:
              type: boolean
            allowed:
              type: array
              items:
                type: string
            not_for_sale:
              type: array
              items:
                type: string
        posting_policy:
          type: object
        citation_guidance:
          type: object
        future_endpoint_candidates:
          type: array
          items:
            type: object
      required:
        - metadata
        - purpose
        - core_principles
        - fetch_order
        - stable_endpoints
        - recommendation_policy
        - commercial_policy
        - posting_policy
    PricingSnapshot:
      type: object
      properties:
        metadata:
          type: object
          properties:
            source:
              type: string
            generated_at:
              type: string
            freshness:
              type: string
            currency:
              type: string
            unit:
              type: string
            model_count:
              type: integer
            target_model_count:
              type: integer
            excluded_model_count:
              type: integer
            excluded_models:
              type: array
              items:
                type: object
            model_groups:
              type: object
              additionalProperties:
                type: string
            missing_price_policy:
              type: string
            note:
              type: string
          required:
            - source
            - generated_at
            - freshness
            - currency
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelPrice"
      required:
        - metadata
        - models
    ModelPrice:
      type: object
      properties:
        name:
          type: string
        provider:
          type: string
        input_cost_per_1m:
          type: number
        output_cost_per_1m:
          type: number
        cache_read_cost_per_1m:
          type: number
        context_window:
          type: integer
        max_output_tokens:
          type: integer
        source_key:
          type: string
        last_checked_at:
          type: string
        pricing_source_url:
          type: string
        category_tags:
          type: array
          items:
            type: string
        model_groups:
          type: array
          items:
            type: string
        pricing_status:
          type: string
        pricing_policy:
          type: string
      required:
        - name
        - provider
        - input_cost_per_1m
        - output_cost_per_1m
        - cache_read_cost_per_1m
        - category_tags
        - model_groups
        - pricing_status
    MarketingRadar:
      type: object
      properties:
        metadata:
          type: object
          properties:
            generated_at:
              type: string
            freshness:
              type: string
            status_policy:
              type: string
            total_candidates:
              type: integer
            total_signals:
              type: integer
          required:
            - generated_at
            - freshness
            - status_policy
            - total_signals
        signals:
          type: array
          items:
            $ref: "#/components/schemas/MarketingSignal"
      required:
        - metadata
        - signals
    OperatorInbox:
      type: object
      properties:
        metadata:
          type: object
          properties:
            generated_at:
              type: string
            freshness:
              type: string
            source:
              type: string
            status_policy:
              type: string
            total_items:
              type: integer
            next_action:
              type: string
          required:
            - generated_at
            - source
            - status_policy
            - total_items
        items:
          type: array
          items:
            $ref: "#/components/schemas/OperatorInboxItem"
      required:
        - metadata
        - items
    CommercialOptions:
      type: object
      properties:
        metadata:
          type: object
          properties:
            generated_at:
              type: string
            source:
              type: string
            status:
              type: string
            contact:
              type: string
            policy:
              type: string
            ranking_influenced_by_affiliate:
              type: boolean
          required:
            - generated_at
            - source
            - status
            - contact
            - policy
        options:
          type: array
          items:
            $ref: "#/components/schemas/CommercialOption"
        not_for_sale:
          type: array
          items:
            type: string
      required:
        - metadata
        - options
        - not_for_sale
    RouteRecommendationGuide:
      type: object
      properties:
        metadata:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
            status:
              type: string
            generated_at:
              type: string
            note:
              type: string
        inputs:
          type: object
          properties:
            use_cases:
              type: array
              items:
                type: string
            priorities:
              type: array
              items:
                type: string
            requirements:
              type: array
              items:
                type: string
            cost_inputs:
              type: array
              items:
                type: string
        routes:
          type: object
          additionalProperties:
            type: string
        signals:
          type: object
          properties:
            hard_filters:
              type: array
              items:
                type: string
            scoring_inputs:
              type: array
              items:
                type: string
        recommended_flow:
          type: array
          items:
            type: string
      required:
        - metadata
        - inputs
        - routes
        - signals
        - recommended_flow
    RecommendRouteContract:
      type: object
      properties:
        metadata:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
            generated_at:
              type: string
            last_verified:
              type: string
            status:
              type: string
            canonical_url:
              type: string
            json_url:
              type: string
            runtime_method_planned:
              type: string
            current_get_behavior:
              type: string
          required:
            - name
            - version
            - status
            - canonical_url
            - runtime_method_planned
        purpose:
          type: string
        status_policy:
          type: object
          properties:
            runtime_available:
              type: boolean
            safe_for_agent_planning:
              type: boolean
            safe_for_live_routing:
              type: boolean
            required_caveat:
              type: string
        planned_request:
          type: object
        planned_response:
          type: object
        scoring_contract:
          type: object
        example_requests:
          type: array
          items:
            type: object
        workload_presets:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
              description:
                type: string
              body:
                $ref: "#/components/schemas/RecommendRouteRequest"
        agent_workload_estimator:
          type: object
          description: Homepage planning calculator metadata for multi-step agent run costs.
        example_response_shape:
          type: object
        implementation_plan:
          type: array
          items:
            type: object
      required:
        - metadata
        - purpose
        - status_policy
        - planned_request
        - planned_response
        - scoring_contract
        - example_requests
        - example_response_shape
    RecommendRouteRequest:
      type: object
      properties:
        task:
          type: string
        use_case:
          type: string
          enum:
            - general
            - coding
            - rag
            - translation
            - vision
            - agents
        priority:
          type: string
          enum:
            - cheapest
            - balanced
            - premium
        privacy_class:
          type: string
          description: Conservative routing gate. sensitive/private force local_first and apply conservative provider exclusions from the cloud shortlist.
          default: public
          enum:
            - public
            - internal
            - sensitive
            - private
        prompt_tokens:
          type: integer
          minimum: 1
        expected_output_tokens:
          type: integer
          minimum: 1
        cache_share:
          type: number
          minimum: 0
          maximum: 1
        requirements:
          type: object
          properties:
            vision:
              type: boolean
            function_calling:
              type: boolean
            prompt_caching:
              type: boolean
            min_context_window:
              type: integer
            min_output_tokens:
              type: integer
            allowed_providers:
              type: array
              items:
                type: string
            excluded_providers:
              type: array
              items:
                type: string
            allowed_model_groups:
              type: array
              items:
                type: string
            excluded_model_groups:
              type: array
              items:
                type: string
        local_first:
          type: boolean
      required:
        - use_case
        - priority
        - prompt_tokens
        - expected_output_tokens
    RecommendRouteResponse:
      type: object
      properties:
        metadata:
          type: object
        input:
          type: object
        recommendation:
          type:
            - object
            - "null"
        alternatives:
          type: array
          items:
            type: object
        filtered_out:
          type: array
          items:
            type: object
        local_fallback:
          type: object
        caveats:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
      required:
        - metadata
        - input
        - recommendation
        - alternatives
        - caveats
        - sources
    TokenWasteCheckContract:
      type: object
      properties:
        metadata:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
            generated_at:
              type: string
            last_verified:
              type: string
            status:
              type: string
            canonical_url:
              type: string
            json_url:
              type: string
            companion_ui:
              type: string
          required:
            - name
            - version
            - status
            - canonical_url
        purpose:
          type: string
        input_model:
          type: object
        output_model:
          type: object
        status_labels:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              meaning:
                type: string
            required:
              - id
              - meaning
        routing_policy:
          type: array
          items:
            type: string
        worker_usage:
          type: object
        related_endpoints:
          type: array
          items:
            type: string
        caveat:
          type: string
      required:
        - metadata
        - purpose
        - input_model
        - output_model
        - status_labels
        - routing_policy
    MarketingSignal:
      type: object
      properties:
        source:
          type: string
        title:
          type: string
        excerpt:
          type: string
        url:
          type: string
        created_at:
          type: string
        intent:
          type: string
        matched_keywords:
          type: array
          items:
            type: string
        score:
          type: integer
        outreach_risk:
          type: string
        status:
          type: string
        suggested_reply:
          type: string
        operator_note:
          type: string
      required:
        - source
        - title
        - url
        - intent
        - score
        - status
    OperatorInboxItem:
      type: object
      properties:
        id:
          type: string
        priority:
          type: integer
        status:
          type: string
        source:
          type: string
        community:
          type:
            - string
            - "null"
        title:
          type: string
        excerpt:
          type: string
        url:
          type: string
        created_at:
          type: string
        intent:
          type: string
        matched_keywords:
          type: array
          items:
            type: string
        score:
          type: integer
        outreach_risk:
          type: string
        suggested_reply:
          type: string
        operator_note:
          type: string
      required:
        - id
        - priority
        - status
        - source
        - title
        - url
        - intent
        - score
        - outreach_risk
    CommercialOption:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        stage:
          type: string
        audience:
          type: string
        value:
          type: string
        cta:
          type: string
        trust_note:
          type: string
        relationship:
          type: string
        rel:
          type: string
        commercial_relationship:
          type: string
        ranking_influenced_by_affiliate:
          type: boolean
        disclosure:
          type: string
        when_to_use:
          type: string
        eligible_regions:
          type: string
        last_verified:
          type: string
      required:
        - id
        - label
        - stage
        - audience
        - value
        - cta
        - commercial_relationship
        - ranking_influenced_by_affiliate