> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Chat Completion

> Create a model response for a chat conversation with intelligent routing

Creates a model response for the given chat conversation.

Auriko routes the request to the optimal provider based on your routing preferences (cost, latency, throughput, etc.).

## Auriko Extensions

Beyond OpenAI compatibility, this endpoint supports:

* **Multi-model routing**: Use `models[]` instead of `model` to route across multiple models
* **Routing options**: Control provider selection with the `routing` object
* **Provider extensions**: Pass provider-specific parameters with `extensions`
* **Cost transparency**: Response includes `routing_metadata` with cost breakdown

<Note>
  All parameters, request/response schemas, and examples are auto-generated from the [OpenAPI specification](/api-reference/overview).
</Note>


## OpenAPI

````yaml POST /v1/chat/completions
openapi: 3.1.0
info:
  title: Auriko API
  version: 1.0.0
  description: >
    Intelligent LLM routing API with OpenAI-compatible interface.


    ## Overview


    Auriko provides a unified API for accessing multiple LLM providers with
    intelligent

    routing based on cost, latency, throughput, and availability.


    ## OpenAI Compatibility


    The API is compatible with OpenAI's Chat Completions API. You can use any

    OpenAI SDK by changing the base URL and API key.


    ## Auriko Extensions


    Beyond OpenAI compatibility, Auriko adds:


    - **Multi-model routing**: Request multiple models with `gateway.models[]`
    array

    - **Routing options**: Control provider selection with `routing` object

    - **Provider extensions**: Pass provider-specific parameters with
    `extensions` object

    - **Routing metadata**: Get transparency into routing decisions via
    `routing_metadata`
  contact:
    name: Auriko Support
    url: https://auriko.ai
  license:
    name: Proprietary
    url: https://auriko.ai/terms
servers:
  - url: https://api.auriko.ai
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Chat
    description: Chat completion endpoints
  - name: Responses
    description: OpenAI Response API endpoints
  - name: Callable Models
    description: Model IDs available for authenticated inference requests
  - name: Model Catalog
    description: Public model and provider catalog endpoints
  - name: Workspaces
    description: Workspace management
  - name: Budgets
    description: Spend control and budget management
  - name: API Keys
    description: API key management
  - name: BYOK
    description: Bring-your-own-key provider key management
  - name: Billing
    description: Credit balance and billing
  - name: Account
    description: API key introspection
  - name: Messages
    description: Anthropic Messages API endpoints
  - name: Routing
    description: Workspace routing configuration
  - name: Usage
    description: Usage statistics and request lookup
  - name: Members
    description: Workspace member and invite management
  - name: Audit
    description: Workspace audit event log
paths:
  /v1/chat/completions:
    post:
      tags:
        - Chat
      summary: Create a chat completion
      description: >
        Creates a model response for the given chat conversation.


        Auriko routes the request to the optimal provider based on your

        routing preferences (cost, latency, throughput, etc.).


        ## Streaming


        When `stream: true`, responses are delivered as Server-Sent Events
        (SSE).

        The final event contains `routing_metadata` with routing decision
        details.


        ## Multi-Model Routing


        Use `gateway.models[]` instead of top-level `model` to enable
        multi-model routing:

        - `gateway.routing.mode: "pool"` (default): Best provider across all
        models

        - `gateway.routing.mode: "fallback"`: Try models in order
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: Basic completion
                value:
                  model: gpt-4o
                  messages:
                    - role: user
                      content: Hello!
              with_routing:
                summary: With routing options
                value:
                  model: claude-sonnet-4-6
                  messages:
                    - role: user
                      content: Explain quantum computing
                  gateway:
                    routing:
                      optimize: cost
                      max_cost_per_1m: 10
              multi_model:
                summary: Multi-model routing
                value:
                  gateway:
                    models:
                      - gpt-4o
                      - claude-sonnet-4-6
                    routing:
                      mode: pool
                      optimize: cost
                  messages:
                    - role: user
                      content: Hello!
      responses:
        '200':
          description: >
            Successful completion.


            For streaming (`stream: true`), responses are Server-Sent Events.

            Each event is a `ChatCompletionChunk`. The final chunk has `choices:
            []`

            (empty) and contains `usage` and `routing_metadata`. Stream ends
            with

            `data: [DONE]`.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-RateLimit-Limit-Requests:
              description: Request limit per window
              schema:
                type: integer
              example: 60
            X-RateLimit-Remaining-Requests:
              description: Remaining requests in current window
              schema:
                type: integer
              example: 57
            X-RateLimit-Reset-Requests:
              description: When the rate limit window resets (ISO 8601)
              schema:
                type: string
                format: date-time
              example: '2026-06-15T12:01:00.000Z'
            X-Credits-Balance-Microdollars:
              description: >-
                Current workspace credit balance in microdollars (1 USD =
                1,000,000)
              schema:
                type: integer
              example: 4850000
            X-Budget-Daily-Spend:
              description: Daily budget spend in USD (present when daily budget exists)
              schema:
                type: string
              example: '1.23'
            X-Budget-Daily-Limit:
              description: Daily budget limit in USD (present when daily budget exists)
              schema:
                type: string
              example: '10.00'
            X-Budget-Weekly-Spend:
              description: Weekly budget spend in USD (present when weekly budget exists)
              schema:
                type: string
              example: '8.50'
            X-Budget-Weekly-Limit:
              description: Weekly budget limit in USD (present when weekly budget exists)
              schema:
                type: string
              example: '50.00'
            X-Budget-Monthly-Spend:
              description: Monthly budget spend in USD (present when monthly budget exists)
              schema:
                type: string
              example: '35.00'
            X-Budget-Monthly-Limit:
              description: Monthly budget limit in USD (present when monthly budget exists)
              schema:
                type: string
              example: '200.00'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
              example:
                id: chatcmpl-abc123
                object: chat.completion
                created: 1745100000
                model: gpt-4o-2024-08-06
                choices:
                  - index: 0
                    message:
                      role: assistant
                      content: The capital of France is Paris.
                    logprobs: null
                    finish_reason: stop
                usage:
                  prompt_tokens: 14
                  completion_tokens: 7
                  total_tokens: 21
                  prompt_tokens_details:
                    cached_tokens: 0
                  completion_tokens_details:
                    reasoning_tokens: 0
                system_fingerprint: fp_d08c293973
                routing_metadata:
                  provider: openai
                  provider_model_id: gpt-4o-2024-08-06
                  model_canonical: gpt-4o
                  routing_strategy: cost-focus
                  throughput_tps: 9.2
                  cost:
                    usd: 0.000105
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ChatCompletionSSE'
              example: >
                data:
                {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1745100000,"model":"gpt-4o-2024-08-06","system_fingerprint":"fp_d08c293973","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}


                data:
                {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1745100000,"model":"gpt-4o-2024-08-06","system_fingerprint":"fp_d08c293973","choices":[{"index":0,"delta":{"content":"The"},"logprobs":null,"finish_reason":null}]}


                ....


                data:
                {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1745100000,"model":"gpt-4o-2024-08-06","system_fingerprint":"fp_d08c293973","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}


                data:
                {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1745100000,"model":"gpt-4o-2024-08-06","system_fingerprint":"fp_d08c293973","choices":[],"usage":{"prompt_tokens":14,"completion_tokens":7,"total_tokens":21}}


                data:
                {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1745100000,"model":"gpt-4o-2024-08-06","choices":[],"routing_metadata":{"provider":"openai","provider_model_id":"gpt-4o-2024-08-06","model_canonical":"gpt-4o","routing_strategy":"cost-focus","ttft_ms":977,"throughput_tps":350,"cost":{"usd":0.000105}}}


                data: [DONE]
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ModelNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/ProviderError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/ProviderTimeout'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/chat/completions \
              -H "Authorization: Bearer $AURIKO_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "gpt-4o",
                "messages": [{"role": "user", "content": "Hello"}]
              }'
        - lang: python
          label: Python
          source: |
            from auriko import Client

            client = Client()
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": "Hello"}]
            )
            print(response.choices[0].message.content)
        - lang: typescript
          label: TypeScript
          source: |
            import { Client } from "@auriko/sdk";

            const client = new Client();
            const response = await client.chat.completions.create({
                model: "gpt-4o",
                messages: [{ role: "user", content: "Hello" }],
            });
            console.log(response.choices[0].message.content);
        - lang: python
          label: Python (with gateway.metadata)
          source: |
            from auriko import Client
            from auriko.route_types import GatewayOptions

            client = Client()
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": "Hello"}],
                gateway=GatewayOptions(
                    metadata={
                        "tags": ["production", "gpt-4o"],
                        "user_id": "user_123",
                        "custom_fields": {"env": "production"},
                    },
                ),
            )
            print(response.choices[0].message.content)
        - lang: python
          label: Python (OpenAI-compatible)
          source: |
            import os
            from openai import OpenAI

            client = OpenAI(
                api_key=os.environ["AURIKO_API_KEY"],
                base_url="https://api.auriko.ai/v1"
            )
            response = client.chat.completions.create(
                model="gpt-4o",
                messages=[{"role": "user", "content": "Hello"}]
            )
            print(response.choices[0].message.content)
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - messages
      oneOf:
        - required:
            - model
        - required:
            - gateway
          properties:
            gateway:
              required:
                - models
      properties:
        model:
          type: string
          example: gpt-4o
          description: >
            Model to route to, required for single-model requests.

            Mutually exclusive with `gateway.models`; providing both returns
            400.


            Examples: `gpt-4o`, `claude-sonnet-4-6`, `llama-3.3-70b-instruct`
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          minItems: 1
          description: The messages to generate a completion for
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: >-
            Sampling temperature (0-2). Some providers restrict this value when
            reasoning is enabled.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Nucleus sampling parameter. Some providers restrict this value when
            reasoning is enabled.
        max_tokens:
          type: integer
          minimum: 1
          description: Maximum tokens to generate (legacy, use `max_completion_tokens`)
        max_completion_tokens:
          type: integer
          minimum: 1
          description: >-
            Maximum tokens to generate. Reasoning models (o1/o3) use this field
            instead of `max_tokens`.
        reasoning_effort:
          type: string
          enum:
            - low
            - medium
            - high
            - xhigh
            - max
            - 'off'
          description: |
            Controls reasoning effort for supported models. Auriko translates
            this into each provider's native reasoning control.

            See /guides/extensions-and-thinking for per-provider behavior.
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 4
          description: Stop sequences. Restrictions vary by provider and model.
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: Presence penalty (-2 to 2). Not supported by all providers.
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
          description: Frequency penalty (-2 to 2). Not supported by all providers.
        logit_bias:
          type: object
          additionalProperties:
            type: number
          description: Token logit bias. Not supported by all providers.
        seed:
          type: integer
          description: Random seed for reproducibility
        top_k:
          type: integer
          minimum: 1
          description: >-
            Top-K sampling. Restricted by some providers when reasoning is
            enabled. Supported by Anthropic, Google, and vLLM.
        min_p:
          type: number
          minimum: 0
          maximum: 1
          description: Min-P sampling. Supported by some vLLM providers.
        top_a:
          type: number
          minimum: 0
          maximum: 1
          description: Top-A sampling. Supported by some vLLM providers.
        repetition_penalty:
          type: number
          description: Repetition penalty. Supported by vLLM providers.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/Tool'
          description: Tools the model can call
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        parallel_tool_calls:
          type: boolean
          description: Allow parallel tool calls
        functions:
          type: array
          items:
            $ref: '#/components/schemas/FunctionDefinition'
          deprecated: true
          description: Deprecated. Use `tools` instead. Auto-converted.
        function_call:
          deprecated: true
          description: Deprecated. Use `tool_choice` instead. Auto-converted.
          oneOf:
            - type: string
              enum:
                - none
                - auto
            - type: object
              required:
                - name
              properties:
                name:
                  type: string
        response_format:
          $ref: '#/components/schemas/ResponseFormat'
        stream:
          type: boolean
          default: false
          description: Enable streaming responses
        stream_options:
          $ref: '#/components/schemas/StreamOptions'
        user:
          type: string
          description: User identifier for abuse detection
        'n':
          type: integer
          minimum: 1
          maximum: 10
          default: 1
          description: Number of completions to generate. Not supported by all providers.
        logprobs:
          type: boolean
          description: Return log probabilities. Not supported by all providers.
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
          description: Number of top logprobs to return. Requires logprobs support.
        web_search_options:
          type: object
          description: Web search configuration. Supported by OpenAI.
          additionalProperties: true
        verbosity:
          type: string
          description: Output verbosity control. Supported by OpenAI.
        prompt_cache_key:
          type: string
          description: Prompt caching identifier. Supported by OpenAI.
        safety_identifier:
          type: string
          description: Safety policy identifier. Supported by OpenAI.
        gateway:
          type: object
          description: >-
            Auriko routing, metadata, and multi-model configuration. Omit for
            default single-model routing.
          properties:
            routing:
              $ref: '#/components/schemas/RoutingOptions'
            metadata:
              $ref: '#/components/schemas/RequestMetadata'
            models:
              type: array
              items:
                type: string
              minItems: 1
              maxItems: 10
              description: >
                Multi-model routing. Mutually exclusive with top-level `model`.
                Providing both `model` and `gateway.models` returns 400. Models
                are tried in order per routing mode.
          additionalProperties: false
        extensions:
          $ref: '#/components/schemas/Extensions'
    ChatCompletionResponse:
      type: object
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
          description: Unique completion identifier
        object:
          type: string
          const: chat.completion
        created:
          type: integer
          description: Unix timestamp of creation
        model:
          type: string
          description: Model used for completion
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
          description: Completion choices
        usage:
          $ref: '#/components/schemas/Usage'
          description: >
            Token usage statistics. Present in virtually all responses.

            May be absent in rare cases where upstream provider does not report
            usage.
        system_fingerprint:
          type: string
          description: >-
            Backend fingerprint for reproducibility. Not all models include this
            field.
        routing_metadata:
          $ref: '#/components/schemas/RoutingMetadata'
        service_tier:
          type:
            - string
            - 'null'
          description: >-
            The service tier used for processing the request. Present for
            OpenAI-routed models.
    ChatCompletionSSE:
      type: object
      description: >
        Server-Sent Event wrapper for chat completion streaming.


        Per SSE specification, events can have four fields: `id`, `event`,
        `data`, `retry`.

        OpenAI's streaming format uses only the `data` field, containing the
        chunk JSON.


        Example SSE line from the API:

        ```

        data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk",...}

        ```
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/ChatCompletionChunk'
    Message:
      oneOf:
        - $ref: '#/components/schemas/SystemMessage'
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/AssistantMessage'
        - $ref: '#/components/schemas/ToolMessage'
        - $ref: '#/components/schemas/DeveloperMessage'
        - $ref: '#/components/schemas/FunctionMessage'
      discriminator:
        propertyName: role
        mapping:
          system:
            $ref: '#/components/schemas/SystemMessage'
          user:
            $ref: '#/components/schemas/UserMessage'
          assistant:
            $ref: '#/components/schemas/AssistantMessage'
          tool:
            $ref: '#/components/schemas/ToolMessage'
          developer:
            $ref: '#/components/schemas/DeveloperMessage'
          function:
            $ref: '#/components/schemas/FunctionMessage'
    Tool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          const: function
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    ToolChoice:
      oneOf:
        - type: string
          enum:
            - auto
            - required
            - none
        - type: object
          required:
            - type
            - function
          properties:
            type:
              type: string
              const: function
            function:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
    FunctionDefinition:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Function name
        description:
          type: string
          description: Function description
        parameters:
          type: object
          description: JSON Schema for function parameters
          additionalProperties: true
        strict:
          type: boolean
          description: Enable strict mode for structured outputs
    ResponseFormat:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - json_object
            - json_schema
          description: |
            Response format type:
            - `text`: Plain text response (default)
            - `json_object`: JSON mode - model outputs valid JSON
            - `json_schema`: Structured output - model follows provided schema
        json_schema:
          type: object
          description: Required when type is `json_schema`
          required:
            - name
            - schema
          properties:
            name:
              type: string
              description: Schema name (required)
            description:
              type: string
              description: Schema description
            schema:
              type: object
              description: JSON Schema definition
              additionalProperties: true
            strict:
              type: boolean
              description: Enable strict schema validation
    StreamOptions:
      type: object
      properties:
        include_usage:
          type: boolean
          description: Include token usage in final streaming chunk
    RoutingOptions:
      type: object
      description: >
        Auriko routing configuration (20 fields).


        Controls how Auriko selects providers for your request.

        All fields are optional. Setting a field to `null` is equivalent to
        omitting it.
      properties:
        optimize:
          type:
            - string
            - 'null'
          enum:
            - cost
            - cost-focus
            - ttft
            - ttft-focus
            - tps
            - tps-focus
            - balanced
            - null
          default: cost-focus
          description: |
            Optimization strategy:
            - `cost`: Minimize cost per token (well-rounded)
            - `cost-focus`: Aggressively minimize cost (default)
            - `ttft`: Minimize time to first token (well-rounded)
            - `ttft-focus`: Aggressively minimize time to first token
            - `tps`: Maximize tokens per second (well-rounded)
            - `tps-focus`: Aggressively maximize tokens per second
            - `balanced`: All dimensions weighted evenly
        weights:
          type:
            - object
            - 'null'
          additionalProperties: false
          description: >
            Custom scoring weights for routing optimization.

            When provided, overrides the `optimize` preset coefficients.

            All values must be non-negative. At least one dimension must be > 0.

            Unspecified dimensions default to 0. Server normalizes to sum to
            1.0.
          properties:
            cost:
              type:
                - number
                - 'null'
              minimum: 0
              description: Weight for cost minimization.
            ttft:
              type:
                - number
                - 'null'
              minimum: 0
              description: Weight for time-to-first-token optimization.
            throughput:
              type:
                - number
                - 'null'
              minimum: 0
              description: Weight for tokens-per-second optimization.
        ttft_percentile:
          type:
            - string
            - 'null'
          enum:
            - p50
            - p95
            - null
          default: p50
          description: >
            Which percentile to use for TTFT metrics in scoring and constraint
            filtering.

            p50 uses median, p95 uses worst-case. Default: p50.
        throughput_percentile:
          type:
            - string
            - 'null'
          enum:
            - p50
            - p95
            - null
          default: p50
          description: >
            Which percentile to use for throughput metrics in scoring and
            constraint filtering.

            p50 uses median, p95 uses worst-case. Default: p50.
        max_cost_per_1m:
          type:
            - number
            - 'null'
          exclusiveMinimum: 0
          description: |
            Maximum cost per 1 million tokens (USD).
            Providers exceeding this cost are excluded from selection.
        max_ttft_ms:
          type:
            - integer
            - 'null'
          exclusiveMinimum: 0
          description: |
            Maximum time to first token in milliseconds.
            Providers with estimated TTFT above this threshold are excluded.
        min_throughput_tps:
          type:
            - number
            - 'null'
          exclusiveMinimum: 0
          description: >
            Minimum throughput in tokens per second.

            Providers with estimated throughput below this threshold are
            excluded.
        providers:
          type:
            - array
            - 'null'
          items:
            type: string
          description: |
            Provider allowlist. Only consider these providers.

            Examples: `["openai", "anthropic", "fireworks_ai"]`
        exclude_providers:
          type:
            - array
            - 'null'
          items:
            type: string
          description: |
            Provider blocklist. Exclude these providers.

            Examples: `["together_ai"]`
        prefer:
          type:
            - string
            - 'null'
          description: |
            Preference boost for this provider.
            Provider will be selected if it meets constraints.
        mode:
          type:
            - string
            - 'null'
          enum:
            - pool
            - fallback
            - null
          default: pool
          description: |
            How to interpret `gateway.models[]` array:
            - `pool` (default): Route to best provider across all models
            - `fallback`: Try models in order until one succeeds
        allow_fallbacks:
          type:
            - boolean
            - 'null'
          default: true
          description: Enable automatic fallback to alternative providers on failure
        max_fallback_attempts:
          type:
            - integer
            - 'null'
          minimum: 1
          maximum: 19
          default: 19
          description: >-
            Maximum fallback attempts before giving up (chain length 20 =
            primary + 19 fallbacks). Range: 1-19.
        timeout_ms:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >
            Per-attempt timeout in milliseconds. For streaming requests: time to
            first SSE byte. For non-streaming requests: time to complete
            response. Default: 120000 (120s streaming first-byte), 300000 (5min
            non-streaming total).
        deadline_ms:
          type:
            - integer
            - 'null'
          minimum: 1
          description: >
            Request deadline in milliseconds. Hard wall-clock cap across all
            fallback attempts. Must be >= timeout_ms when both are set.
            Non-streaming requests default to 1080000 (18 minutes); streaming
            has no default.
        data_policy:
          type:
            - string
            - 'null'
          enum:
            - none
            - no_training
            - zdr
            - null
          default: none
          description: |
            Data retention policy requirement:
            - `none`: No restrictions (default)
            - `no_training`: Provider must not use data for training
            - `zdr`: Zero Data Retention (strictest)
        only_byok:
          type:
            - boolean
            - 'null'
          default: false
          description: >
            Only use Bring Your Own Key (BYOK) providers.

            Mutually exclusive with `only_platform`. Returns 400 if both are
            set.
        only_platform:
          type:
            - boolean
            - 'null'
          default: false
          description: |
            Only use platform-managed API keys.
            Mutually exclusive with `only_byok`. Returns 400 if both are set.
        require_parameters:
          type:
            - boolean
            - 'null'
          default: false
          description: |
            When true, only route to providers whose accepted_params includes
            all optional parameters sent in this request. Default: false.
        tier:
          type:
            - string
            - 'null'
          description: >
            Opt in to a pricing tier. Currently supported: `priority` (Anthropic
            fast mode — 2.5x speed at 6x cost).

            Note: Auriko's "priority" tier refers to Anthropic Fast Mode, not
            Anthropic's separate Priority Tier (committed capacity SLA).

            Omitting this field (default) excludes premium-tier offerings from
            routing.
          enum:
            - priority
            - null
    RequestMetadata:
      type: object
      description: |
        Optional request metadata for tracking and observability.
        Attached via the `gateway.metadata` field on chat completion requests.
      properties:
        tags:
          type: array
          items:
            type: string
            maxLength: 50
          maxItems: 100
          description: Tags for categorizing requests (max 100 items, each ≤50 chars)
        user_id:
          type: string
          maxLength: 255
          description: Your application's user identifier for per-user analytics
        trace_id:
          type: string
          maxLength: 255
          description: >-
            Distributed tracing identifier to correlate with your observability
            stack
        custom_fields:
          type: object
          maxProperties: 10
          additionalProperties:
            type: string
            maxLength: 200
          description: >
            Arbitrary key-value pairs (max 10 keys, keys ≤50 chars, values ≤200
            chars)
      additionalProperties: false
    Extensions:
      type: object
      description: |
        Auriko extensions for provider-specific passthrough.

        For reasoning control, use the top-level `reasoning_effort` parameter
        instead of extensions.

        ## Provider Passthrough

        Pass provider-specific parameters directly:
        - `anthropic`: Anthropic-specific parameters
        - `openai`: OpenAI-specific parameters
        - `google`: Google/Gemini-specific parameters
        - `deepseek`: DeepSeek-specific parameters

        Passthrough parameters are forwarded as-is to the target provider.
      properties:
        anthropic:
          type: object
          additionalProperties: true
          description: Anthropic-specific parameters (passed through)
        openai:
          type: object
          additionalProperties: true
          description: OpenAI-specific parameters (passed through)
        google:
          type: object
          additionalProperties: true
          description: Google/Gemini-specific parameters (passed through)
        deepseek:
          type: object
          additionalProperties: true
          description: DeepSeek-specific parameters (passed through)
      additionalProperties:
        type: object
        description: Other provider-specific passthrough
      not:
        required:
          - thinking
    Choice:
      type: object
      required:
        - index
        - message
        - finish_reason
      properties:
        index:
          type: integer
          description: Choice index
        message:
          type: object
          required:
            - role
          properties:
            role:
              type: string
              const: assistant
            content:
              type:
                - string
                - 'null'
              description: Response content
            tool_calls:
              type: array
              items:
                $ref: '#/components/schemas/ToolCall'
              description: Tool calls requested by the model
            reasoning_content:
              type: string
              description: >
                Thinking/reasoning content from reasoning models.

                Present when using models like o1, DeepSeek R1, or Claude with
                thinking.
            reasoning:
              type: array
              items:
                $ref: '#/components/schemas/ReasoningBlock'
              description: >
                Structured reasoning blocks with cryptographic signatures.

                Present alongside reasoning_content for models that support
                signed thinking.
            refusal:
              type:
                - string
                - 'null'
              description: >-
                Refusal message if the model declined to answer. Present for
                OpenAI-routed models.
            images:
              type: array
              items:
                $ref: '#/components/schemas/GeneratedImage'
              description: >-
                Generated images from image-capable models. Present when the
                model produces image output (e.g., Gemini image models). Absent
                (not null, not empty array) when no images are generated.
            annotations:
              type: array
              items: {}
              description: >-
                Model annotations such as URL citations. Present for
                OpenAI-routed models.
        finish_reason:
          type:
            - string
            - 'null'
          enum:
            - stop
            - length
            - tool_calls
            - content_filter
            - null
          description: |
            Reason generation stopped:
            - `stop`: Natural stop or stop sequence
            - `length`: Max tokens reached
            - `tool_calls`: Model requested tool call
            - `content_filter`: Content was filtered
            - `null`: Generation still in progress (streaming)
        native_finish_reason:
          type:
            - string
            - 'null'
          description: >
            The upstream provider's original finish reason before normalization.
            Present when the provider uses a different vocabulary (e.g.,
            Anthropic 'end_turn', Google 'STOP').
        logprobs:
          type:
            - object
            - 'null'
          description: Log probability information
    Usage:
      type: object
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
      properties:
        prompt_tokens:
          type: integer
          description: Input tokens used
        completion_tokens:
          type: integer
          description: Output tokens generated
        total_tokens:
          type: integer
          description: Total tokens (prompt + completion)
        prompt_tokens_details:
          $ref: '#/components/schemas/PromptTokensDetails'
        completion_tokens_details:
          $ref: '#/components/schemas/CompletionTokensDetails'
    RoutingMetadata:
      type: object
      description: >
        Routing decision metadata included in successful responses.

        8 STABLE fields (4 required + 4 optional) in the current public
        contract.
      required:
        - provider
        - provider_model_id
        - model_canonical
        - routing_strategy
      properties:
        provider:
          type: string
          description: Provider name (e.g., "fireworks_ai", "anthropic")
        provider_model_id:
          type: string
          description: Provider's model ID
        model_canonical:
          type: string
          description: Canonical model ID requested
        routing_strategy:
          type: string
          description: >
            Strategy used for routing. Known values:

            `cost`, `cost-focus`, `ttft`, `ttft-focus`, `tps`, `tps-focus`,
            `balanced`, `custom`.

            `custom` is returned when explicit `routing.weights` are provided.

            Additional strategies may be added in future versions.
        ttft_ms:
          type: number
          description: Time to first token (streaming only)
        throughput_tps:
          type: number
          description: Output throughput (tokens per second)
        cost:
          $ref: '#/components/schemas/CostInfo'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/StructuredWarning'
          description: |
            Structured warnings emitted when the gateway modifies or ignores
            part of the request (e.g., unsupported parameters, blocked fields).
    ChatCompletionChunk:
      type: object
      description: |
        Streaming chunk content (the `data` field payload in SSE).

        ## Final Chunk Format

        The final chunk has `choices: []` (empty array) and contains:
        - `usage`: Token counts (if `stream_options.include_usage: true`)
        - `routing_metadata`: Routing decision details

        This uses standard `chat.completion.chunk` format for SDK compatibility.
      required:
        - id
        - object
        - created
        - model
        - choices
      properties:
        id:
          type: string
          description: Completion identifier (consistent across chunks)
        object:
          type: string
          const: chat.completion.chunk
        created:
          type: integer
          description: Unix timestamp of when the chunk was created
        model:
          type: string
          description: Model that generated the chunk
        choices:
          type: array
          items:
            $ref: '#/components/schemas/StreamChoice'
          description: |
            Streaming choices. Empty array in final metadata chunk.
        usage:
          $ref: '#/components/schemas/Usage'
          description: |
            Token usage. Only present in final chunk when
            `stream_options.include_usage: true` was set.
        system_fingerprint:
          type: string
          description: >-
            Backend fingerprint for reproducibility. Not all models include this
            field.
        routing_metadata:
          $ref: '#/components/schemas/RoutingMetadata'
          description: |
            Auriko extension. Included in final chunk (when choices is empty).
            Contains routing decision transparency data.
        service_tier:
          type:
            - string
            - 'null'
          description: >-
            The service tier used for processing the request. Present for
            OpenAI-routed models.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    SystemMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          const: system
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/SystemContentBlock'
        name:
          type: string
    UserMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          const: user
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
        name:
          type: string
    AssistantMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          const: assistant
        content:
          oneOf:
            - type:
                - string
                - 'null'
            - type: array
              items:
                $ref: '#/components/schemas/TextContentPart'
        name:
          type: string
        tool_calls:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ToolCall'
        reasoning:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ReasoningBlock'
          description: >
            Structured reasoning blocks with cryptographic signatures for
            multi-turn round-trip.
        reasoning_content:
          type:
            - string
            - 'null'
          description: >
            Reasoning content from the model's previous response. Echo back the
            value

            from the assistant message's reasoning_content field for DeepSeek
            multi-turn

            tool calling. Other providers accept but ignore this field.
        refusal:
          type:
            - string
            - 'null'
        function_call:
          deprecated: true
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
    ToolMessage:
      type: object
      required:
        - role
        - content
        - tool_call_id
      properties:
        role:
          type: string
          const: tool
        content:
          type: string
        tool_call_id:
          type: string
    DeveloperMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          const: developer
        content:
          type: string
        name:
          type: string
    FunctionMessage:
      type: object
      deprecated: true
      description: >-
        Deprecated. Use ToolMessage instead. Auriko auto-converts function
        messages to tool messages.
      required:
        - role
        - content
        - name
      properties:
        role:
          type: string
          const: function
        content:
          type:
            - string
            - 'null'
        name:
          type: string
    ToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          const: function
        function:
          type: object
          required:
            - name
            - arguments
          properties:
            name:
              type: string
            arguments:
              type: string
              description: JSON string of function arguments
        provider_signature:
          type: string
          description: >
            Provider-specific cryptographic signature for function-call
            round-trip.

            Echo back on next request for multi-turn correctness.
    ReasoningBlock:
      description: >
        Structured reasoning block from thinking models. Discriminated on
        `type`.

        Used on both request side (AssistantMessage.reasoning) and response side
        (Choice.message.reasoning).
      oneOf:
        - $ref: '#/components/schemas/ThinkingReasoningBlock'
        - $ref: '#/components/schemas/RedactedReasoningBlock'
      discriminator:
        propertyName: type
        mapping:
          thinking:
            $ref: '#/components/schemas/ThinkingReasoningBlock'
          redacted:
            $ref: '#/components/schemas/RedactedReasoningBlock'
    GeneratedImage:
      type: object
      required:
        - type
        - mime_type
        - data
      properties:
        type:
          type: string
          const: image
        mime_type:
          type: string
          description: MIME type of the image (e.g., image/png)
        data:
          type: string
          description: Base64-encoded image data
        thought_signature:
          type: string
          description: >-
            Opaque model signature for multi-turn image editing. Response-only;
            request-side round-trip is not yet supported.
    PromptTokensDetails:
      type: object
      description: Detailed breakdown of prompt tokens
      properties:
        cached_tokens:
          type: integer
          description: Tokens served from cache
        cache_creation_tokens:
          type: integer
          description: Tokens written to prompt cache (Anthropic)
    CompletionTokensDetails:
      type: object
      description: >-
        Breakdown of completion tokens. Provider-dependent: present when the
        upstream provider reports token-level details, absent otherwise.
      properties:
        reasoning_tokens:
          type: integer
          description: >-
            Thinking/reasoning tokens consumed. Present when the upstream
            provider reports this count.
        accepted_prediction_tokens:
          type: integer
          description: >-
            Tokens accepted from a predicted output. Present for OpenAI-routed
            models that support predicted outputs.
        rejected_prediction_tokens:
          type: integer
          description: >-
            Tokens rejected from a predicted output. Present for OpenAI-routed
            models that support predicted outputs.
        image_tokens:
          type: integer
          description: >-
            Tokens consumed by generated images. Present when the upstream
            provider reports image token counts (e.g., Gemini image models).
    CostInfo:
      type: object
      description: Cost for the request
      required:
        - usd
      properties:
        usd:
          type: number
          description: Billable cost in USD
        cache_savings_percent:
          type: integer
          description: >-
            Cache savings as integer percentage (0-100). Present only when
            savings > 0.
        cache_savings_usd:
          type: number
          description: Cache savings in USD. Present only when savings > 0.
    StructuredWarning:
      type: object
      description: |
        Structured warning emitted in routing_metadata.warnings when the
        gateway modifies or ignores part of the request.
      required:
        - type
        - code
        - message
      properties:
        type:
          type: string
          enum:
            - unsupported_parameter
            - unsupported_feature
            - unsupported_field
            - ignored_extension
            - unknown_provider
            - blocked_field
            - provider_timeout
          description: Warning category
        code:
          type: string
          description: >-
            Concrete identifier (parameter name, feature name, provider name, or
            field name)
        message:
          type: string
          description: Human-readable explanation
    StreamChoice:
      type: object
      required:
        - index
        - delta
        - finish_reason
      properties:
        index:
          type: integer
          description: Choice index
        delta:
          type: object
          description: Incremental content delta
          properties:
            role:
              type: string
              enum:
                - assistant
            content:
              type: string
              description: Content fragment
            tool_calls:
              type: array
              items:
                $ref: '#/components/schemas/ToolCallDelta'
              description: Tool call fragments
            reasoning_content:
              type: string
              description: Reasoning content fragment
            reasoning_signature:
              type: string
              description: Cryptographic signature for the current thinking block
            reasoning_redacted_data:
              type: string
              description: >-
                Encrypted data for a redacted thinking block (complete in one
                event)
            refusal:
              type:
                - string
                - 'null'
              description: Refusal content fragment
            images:
              type: array
              items:
                $ref: '#/components/schemas/GeneratedImage'
              description: >-
                Generated images in this streaming chunk. Each image is complete
                (no partial accumulation needed across chunks).
        finish_reason:
          type:
            - string
            - 'null'
          enum:
            - stop
            - length
            - tool_calls
            - content_filter
            - null
          description: Null until generation completes
        native_finish_reason:
          type:
            - string
            - 'null'
          description: >
            The upstream provider's original finish reason before normalization.
            Present when the provider uses a different vocabulary (e.g.,
            Anthropic 'end_turn', Google 'STOP').
        logprobs:
          type:
            - object
            - 'null'
    ErrorObject:
      type: object
      description: OpenAI-compatible error format
      required:
        - message
        - type
        - param
        - code
      properties:
        message:
          type: string
          description: Human-readable error message
        type:
          type: string
          description: Error category per guide §4.
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - api_error
        param:
          type:
            - string
            - 'null'
          description: Parameter that caused the error (null if not applicable)
        code:
          type: string
          description: Canonical code per guide §5 and docs/reference/error_codes.json.
          enum:
            - invalid_api_key
            - expired_api_key
            - insufficient_permissions
            - feature_disabled
            - mfa_required
            - invalid_recovery_code
            - mfa_verification_failed
            - invalid_request
            - missing_required_parameter
            - invalid_parameter_value
            - payload_too_large
            - context_length_exceeded
            - content_filtered
            - idempotency_conflict
            - idempotency_replay_unavailable
            - field_immutable
            - operation_not_allowed
            - unknown_field
            - state_precondition_failed
            - duplicate_resource
            - method_not_allowed
            - tools_not_supported
            - json_mode_not_supported
            - structured_output_not_supported
            - tools_with_structured_output_not_supported
            - vision_not_supported
            - reasoning_not_supported
            - thinking_disable_not_supported
            - streaming_not_supported
            - non_streaming_not_supported
            - batch_only
            - tier_opt_in_required
            - tool_choice_required_not_supported
            - cost_constraint_exceeded
            - latency_constraint_exceeded
            - throughput_constraint_not_met
            - provider_not_in_allowlist
            - provider_blocked
            - required_params_not_supported
            - byok_keys_required
            - platform_keys_unavailable
            - unsupported_modalities
            - no_compatible_endpoint
            - no_responses_endpoint
            - input_requires_responses_endpoint
            - response_api_only
            - hosted_tool_not_supported
            - model_not_found
            - resource_not_found
            - rate_limit_exceeded
            - budget_exhausted
            - insufficient_quota
            - no_provider_available
            - upstream_error
            - upstream_timeout
            - client_disconnected
            - model_unavailable
            - internal_error
            - service_unavailable
        doc_url:
          type: string
          description: Link to the canonical documentation page for this error code.
        provider:
          type:
            - string
            - 'null'
          description: >-
            Upstream provider that generated the error (e.g.,
            "google_ai_studio", "openai"). Null for errors not attributable to
            an upstream provider (local validation, auth, internal config).
        suggestion:
          type: string
          description: >-
            Actionable fix hint for routing, capability, or model-not-found
            errors. Absent for other error types.
    SystemContentBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          const: text
        text:
          type: string
        cache_control:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              const: ephemeral
    ContentPart:
      oneOf:
        - $ref: '#/components/schemas/TextContentPart'
        - $ref: '#/components/schemas/ImageContentPart'
    TextContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          const: text
        text:
          type: string
        cache_control:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              const: ephemeral
    ThinkingReasoningBlock:
      type: object
      required:
        - type
        - thinking
        - signature
      properties:
        type:
          type: string
          const: thinking
        thinking:
          type: string
          description: The model's reasoning content
        signature:
          type: string
          description: Cryptographic signature for multi-turn verification
    RedactedReasoningBlock:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          const: redacted
        data:
          type: string
          description: Opaque encrypted reasoning data (pass through verbatim)
    ToolCallDelta:
      type: object
      description: Partial tool call for streaming
      required:
        - index
      properties:
        index:
          type: integer
          description: Tool call index in the array
        id:
          type: string
        type:
          type: string
          const: function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
        provider_signature:
          type: string
          description: Provider-specific signature for tool call verification (streaming)
    ImageContentPart:
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          const: image_url
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              format: uri
            detail:
              type: string
              enum:
                - auto
                - low
                - high
              default: auto
        cache_control:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              const: ephemeral
  headers:
    X-Request-ID:
      description: |
        Unique request identifier for debugging and support.
        Include this in support requests for fast resolution.
      schema:
        type: string
      example: req_abc123def456
    X-Error-Type:
      description: |
        Same value as the `error.type` field in the response body, exposed as a
        header for programmatic routing without body parsing.
      schema:
        type: string
        enum:
          - invalid_request_error
          - rate_limit_error
          - api_error
          - authentication_error
          - not_found_error
          - permission_error
      example: invalid_request_error
    X-Error-Retryable:
      description: |
        Whether the client should retry this request.
        'true' for api_error and rate_limit_error types; 'false' for all others.
      schema:
        type: string
        enum:
          - 'true'
          - 'false'
      example: 'false'
  responses:
    BadRequest:
      description: Bad request - invalid parameters
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing_model:
              summary: Missing model parameter
              value:
                error:
                  message: 'Missing required parameter: ''model''.'
                  type: invalid_request_error
                  param: model
                  code: missing_required_parameter
            invalid_models:
              summary: Invalid models array
              value:
                error:
                  message: gateway.models array cannot exceed 10 models
                  type: invalid_request_error
                  param: gateway.models
                  code: invalid_request
            vision_not_supported:
              summary: Model doesn't support requested capability
              value:
                error:
                  message: Model 'gpt-4.1-mini' does not support vision/image input.
                  type: invalid_request_error
                  param: null
                  code: vision_not_supported
            cost_constraint_exceeded:
              summary: Routing constraints excluded all providers
              value:
                error:
                  message: No provider meets the cost constraint for model 'gpt-4o'.
                  type: invalid_request_error
                  param: gateway.routing.max_cost_per_1m
                  code: cost_constraint_exceeded
    Unauthorized:
      description: Authentication failed
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: API key is invalid.
              type: authentication_error
              param: null
              code: invalid_api_key
    ModelNotFound:
      description: Model not found
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: >-
                Model 'unknown-model' is not in the catalog. See
                https://api.auriko.ai/v1/directory/models for available models.
              type: not_found_error
              param: model
              code: model_not_found
    RateLimited:
      description: |
        Rate limit exceeded. Two sub-causes share this status:
        - `rate_limit_exceeded`: throughput-based rate limit.
        - `budget_exhausted`: account or project budget reached (self-service;
          not auto-retried by SDKs — requires adding credits or raising the limit).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
        Retry-After:
          description: >-
            Seconds until rate limit resets. Standard HTTP header for retry
            backoff.
          schema:
            type: integer
          example: 60
        X-Rate-Limit-Source:
          description: >-
            Identifies whether the rate limit originated from an upstream
            provider or from Auriko's routing layer.
          schema:
            type: string
            enum:
              - provider
              - routing
          required: false
          example: provider
        X-RateLimit-Limit-Requests:
          description: Request limit per window (present on throughput-based rate limits)
          schema:
            type: integer
          required: false
          example: 60
        X-RateLimit-Remaining-Requests:
          description: >-
            Remaining requests in window (present on throughput-based rate
            limits)
          schema:
            type: integer
          required: false
          example: 0
        X-RateLimit-Reset-Requests:
          description: >-
            When limit resets (ISO 8601 format; present on throughput-based rate
            limits)
          schema:
            type: string
            format: date-time
          required: false
          example: '2026-06-15T12:01:00.000Z'
        X-Budget-Exceeded:
          description: Present on budget-exhaustion 429s.
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          required: false
          example: 'true'
        X-Budget-Exceeded-Period:
          description: Period of the exceeded budget (present on budget-exhaustion 429s).
          schema:
            type: string
            enum:
              - daily
              - weekly
              - monthly
          required: false
          example: monthly
        X-Budget-Exceeded-Scope:
          description: Scope of the exceeded budget (present on budget-exhaustion 429s).
          schema:
            type: string
            enum:
              - workspace
              - api_key
              - byok_provider
          required: false
          example: workspace
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            rate_limit_exceeded:
              summary: Throughput-based rate limit
              value:
                error:
                  message: Rate limit exceeded. Retry after 60 seconds.
                  type: rate_limit_error
                  param: null
                  code: rate_limit_exceeded
            budget_exhausted:
              summary: Account budget exhausted
              value:
                error:
                  message: Account budget exhausted. Add credits to continue.
                  type: rate_limit_error
                  param: null
                  code: budget_exhausted
    InternalError:
      description: Internal server error
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: >-
                An unexpected error occurred. Contact support with the request
                ID.
              type: api_error
              param: null
              code: internal_error
    ProviderError:
      description: >
        Upstream provider failure (Bad Gateway).


        All non-timeout 5xx errors from upstream providers are normalized to 502
        (code: `upstream_error`).

        Upstream failures may also surface as:

        - 429: Provider rate limit (code: `rate_limit_exceeded`)

        - 504: Provider timed out (code: `upstream_timeout`)


        These use their respective status codes with the same `ErrorResponse`
        body format.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          description: Canonical error type (one of the X-Error-Type enum values)
          schema:
            type: string
          required: false
        X-Error-Retryable:
          description: Whether the error is retryable ('true' or 'false')
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          required: false
        Retry-After:
          description: Seconds to wait before retrying (present on rate limit errors)
          schema:
            type: integer
          required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: >-
                Model 'gpt-4o' is temporarily unavailable. Retry in a few
                seconds.
              type: api_error
              param: null
              code: upstream_error
    ServiceUnavailable:
      description: >
        Service unavailable — transient issue. Possible causes:

        - All providers for the model are rate-limited or temporarily
        unavailable (`no_provider_available`)

        - Transient infrastructure issue (`service_unavailable`)


        Note: If the model doesn't support a requested capability (e.g.,
        reasoning),

        the response is 400 with a specific code (e.g.,
        `reasoning_not_supported`), not 503.

        If routing constraints excluded all providers, the response is 400 with
        a

        specific constraint code (e.g., `cost_constraint_exceeded`).
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          $ref: '#/components/headers/X-Error-Type'
        X-Error-Retryable:
          $ref: '#/components/headers/X-Error-Retryable'
        Retry-After:
          description: Seconds to wait before retrying (present on transient failures)
          schema:
            type: integer
          required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            no_providers:
              summary: No providers available for the model
              value:
                error:
                  message: >-
                    No provider available for model 'gpt-4o'. Try a different
                    model.
                  type: api_error
                  param: null
                  code: no_provider_available
            service_unavailable:
              summary: Transient infrastructure issue
              value:
                error:
                  message: Service is temporarily unavailable. Retry in a few seconds.
                  type: api_error
                  param: null
                  code: service_unavailable
    ProviderTimeout:
      description: |
        Upstream provider timed out. The client may retry with a longer timeout.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Error-Type:
          description: Error type (always 'api_error' for timeout responses)
          schema:
            type: string
          required: false
        X-Error-Retryable:
          description: Whether the error is retryable ('true' or 'false')
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: Model 'gpt-4o' timed out. Retry or use a smaller input.
              type: api_error
              param: null
              code: upstream_timeout
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication.
        Keys start with `ak_` prefix.
        Example: `Authorization: Bearer ak_live_xxxxxxxxxxxx`

````