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:
      operationId: createChatCompletion
      x-stability: stable
      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
      security:
        - ApiKeyAuth: []
      tags:
        - Chat
      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)
      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'
  /v1/responses:
    post:
      operationId: createResponse
      x-stability: preview
      summary: Create a response (OpenAI Response API)
      description: >
        Auriko routes the request to the optimal provider based on your

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


        ## Streaming


        When `stream: true`, Auriko delivers responses as Server-Sent Events
        (SSE)

        using the Response API event format: `event: <type>\ndata: <json>\n\n`.


        Terminal events: `response.completed`, `response.incomplete`,
        `response.failed`.

        There's no `data: [DONE]` terminator.


        ## Multi-Model Routing


        Use `gateway.models[]` instead of top-level `model` to enable
        multi-model routing.
      security:
        - ApiKeyAuth: []
      tags:
        - Responses
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/responses \
              -H "Authorization: Bearer $AURIKO_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "gpt-4o",
                "input": "Hello!"
              }'
        - 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.responses.create(
                model="gpt-4o",
                input="Hello!"
            )
            print(response.output_text)
        - lang: typescript
          label: TypeScript (OpenAI-compatible)
          source: |
            import OpenAI from "openai";

            const client = new OpenAI({
                apiKey: process.env.AURIKO_API_KEY,
                baseURL: "https://api.auriko.ai/v1",
            });
            const response = await client.responses.create({
                model: "gpt-4o",
                input: "Hello!",
            });
            console.log(response.output_text);
        - lang: python
          label: Python
          source: |
            from auriko import Client

            client = Client()
            response = client.responses.create(
                model="gpt-4o",
                input="Hello!"
            )
            print(response.output_text)
        - lang: typescript
          label: TypeScript
          source: |
            import { Client } from "@auriko/sdk";

            const client = new Client();
            const response = await client.responses.create({
                model: "gpt-4o",
                input: "Hello!",
            });
            console.log(response.output_text);
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
            examples:
              basic:
                summary: Basic text response
                value:
                  model: gpt-4o
                  input: Hello!
              with_tools:
                summary: With function tools
                value:
                  model: gpt-4o
                  input:
                    - type: message
                      role: user
                      content: What's the weather in NYC?
                  tools:
                    - type: function
                      name: get_weather
                      parameters:
                        type: object
                        properties:
                          city:
                            type: string
      responses:
        '200':
          description: |
            Successful response.

            For non-streaming requests, returns a `ResponseObject`.
            For streaming (`stream: true`), returns Server-Sent Events in
            the Response API format: `event: <type>\ndata: <json>\n\n`.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
              example:
                id: resp_abc123def456
                object: response
                created_at: 1779308695
                model: gpt-4o-2024-08-06
                status: completed
                output:
                  - type: message
                    id: msg_abc123
                    role: assistant
                    status: completed
                    content:
                      - type: output_text
                        text: Hi there! How can I assist you today?
                        annotations: []
                output_text: Hi there! How can I assist you today?
                usage:
                  input_tokens: 9
                  output_tokens: 11
                  total_tokens: 20
                  input_tokens_details:
                    cached_tokens: 0
                    cache_write_tokens: 0
                  output_tokens_details:
                    reasoning_tokens: 0
                routing_metadata:
                  provider: openai
                  provider_model_id: gpt-4o-2024-08-06
                  model_canonical: gpt-4o
                  routing_strategy: cost-focus
                  throughput_tps: 48.3
                  cost:
                    usd: 0.000133
            text/event-stream:
              schema:
                type: string
                description: |
                  Response API SSE stream. Events use the format:
                  `event: <type>\ndata: <json>\n\n`

                  No `data: [DONE]` terminator is used.
        '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'
  /v1/models:
    get:
      operationId: listModels
      x-stability: stable
      summary: List callable models
      description: >
        Returns the OpenAI-compatible model list for your API key.

        Use this endpoint to get model IDs for authenticated inference requests.


        The response includes Auriko fields in addition to OpenAI model fields:

        - `providers[]`: Available providers with pricing

        - `supported_endpoints`: APIs the model supports (e.g.,
        `chat_completions`, `responses`, `batch`)

        - `context_window`: Largest context window across the model's providers

        - `catalog_version`: Version of the model catalog

        - `catalog_age_seconds`: Age of the catalog data


        By default the list contains models callable via Chat Completions.

        Add `?endpoint=responses` to also include models that are only

        available via the Response API.
      security:
        - ApiKeyAuth: []
      tags:
        - Callable Models
      parameters:
        - name: endpoint
          in: query
          required: false
          schema:
            type: string
            enum:
              - chat_completions
              - responses
          description: >
            By default the list contains models callable via Chat Completions

            (`endpoint=chat_completions` is equivalent to omitting the
            parameter).

            Set `endpoint=responses` to also include models that are only

            available via the Response API.
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/models \
              -H "Authorization: Bearer $AURIKO_API_KEY"
        - lang: python
          label: Python
          source: |
            from auriko import Client

            client = Client()
            models = client.models.list()
            for model in models.data:
                print(f"{model.id} — {len(model.providers)} providers")
        - lang: typescript
          label: TypeScript
          source: |
            import { Client } from "@auriko/sdk";

            const client = new Client();
            const models = await client.models.list();
            models.data.forEach((model) => console.log(model.id));
      responses:
        '200':
          description: List of callable models
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
              example:
                object: list
                data:
                  - id: gpt-4o-2024-08-06
                    object: model
                    created: 1776656101
                    owned_by: auriko
                    context_window: 128000
                    supported_endpoints:
                      - assistants
                      - batch
                      - chat_completions
                      - fine_tuning
                      - responses
                    providers:
                      - name: openai
                        input_price: 2.5
                        output_price: 10
                        data_policy: no_training
                catalog_version: 9950bdc087663c7b
                catalog_age_seconds: 120
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/models/{model_id}:
    parameters:
      - name: model_id
        in: path
        required: true
        schema:
          type: string
        description: |
          Canonical model ID or alias. Aliases (e.g. `gpt-4o-mini`) are
          resolved to the canonical ID (e.g. `gpt-4o-mini-2024-07-18`).
    get:
      operationId: getModel
      x-stability: stable
      summary: Retrieve callable model
      description: >
        Returns metadata for one callable model. Accepts canonical model IDs or
        aliases.
      security:
        - ApiKeyAuth: []
      tags:
        - Callable Models
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/models/claude-sonnet-4-6 \
              -H "Authorization: Bearer $AURIKO_API_KEY"
        - lang: python
          label: Python
          source: |
            import os
            from openai import OpenAI

            client = OpenAI(
                base_url="https://api.auriko.ai/v1",
                api_key=os.environ["AURIKO_API_KEY"],
            )
            model = client.models.retrieve("claude-sonnet-4-6")
            print(model.id, model.owned_by)
        - lang: typescript
          label: TypeScript
          source: |
            import OpenAI from "openai";

            const client = new OpenAI({
              baseURL: "https://api.auriko.ai/v1",
              apiKey: process.env.AURIKO_API_KEY,
            });
            const model = await client.models.retrieve("claude-sonnet-4-6");
            console.log(model.id);
      responses:
        '200':
          description: Model details
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
              example:
                id: claude-sonnet-4-6
                object: model
                created: 1776656101
                owned_by: auriko
                context_window: 1000000
                supported_endpoints:
                  - chat_completions
                providers:
                  - name: anthropic
                    input_price: 3
                    output_price: 15
                    data_policy: no_training
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ModelNotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/registry/providers:
    get:
      operationId: listProviders
      x-stability: preview
      x-auriko-auth:
        credential_types: []
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: discovery
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Provider catalog
      description: |
        Returns provider records used in Auriko's model catalog.
      security: []
      tags:
        - Model Catalog
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/registry/providers
      responses:
        '200':
          description: List of providers
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvidersListResponse'
              example:
                providers:
                  - id: openai
                    display_name: OpenAI
                    description: GPT models and APIs
                    icon: openai
                    data_policy: no_training
                count: 10
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/registry/models:
    get:
      operationId: listRegistryModels
      x-stability: preview
      x-auriko-auth:
        credential_types: []
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: discovery
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Canonical model records
      description: |
        Returns compact canonical model records with normalized model IDs,
        capabilities, authors, and provider availability.
      security: []
      tags:
        - Model Catalog
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/registry/models
      responses:
        '200':
          description: Canonical model records
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsListResponse'
              example:
                models:
                  - id: gpt-4o-2024-08-06
                    family: gpt-4o-2024-08-06
                    display_name: GPT-4o
                    capabilities:
                      supports_tools: true
                      supports_vision: true
                      supports_json_mode: true
                      supports_reasoning: false
                      supports_streaming: true
                      supports_web_search: true
                      supports_computer_use: false
                      supports_prompt_caching: false
                      supports_code_interpreter: false
                      supports_structured_output: true
                    input_modalities:
                      - image
                      - text
                    output_modalities:
                      - text
                    author: openai
                    providers:
                      - openai
                    has_free_provider: false
                count: 127
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/directory/models:
    get:
      operationId: listDirectoryModels
      x-stability: preview
      x-auriko-auth:
        credential_types: []
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: discovery
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Model directory
      description: |
        Returns the full model catalog with provider routes, context windows,
        capabilities, modalities, and pricing tiers.
      security: []
      tags:
        - Model Catalog
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/directory/models
      responses:
        '200':
          description: Model directory
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryResponse'
              example:
                models:
                  gpt-4o-2024-08-06:
                    family: gpt-4o-2024-08-06
                    author: openai
                    display_name: GPT-4o
                    providers:
                      - provider: openai
                        provider_model_id: gpt-4o-2024-08-06
                        context_window: 128000
                        max_output_tokens: 16384
                        capabilities:
                          supports_streaming: true
                          supports_tools: true
                          supports_json_mode: true
                          supports_vision: true
                          supports_reasoning: false
                          supports_prompt_caching: false
                          supports_computer_use: false
                          supports_web_search: true
                          supports_code_interpreter: false
                          supports_structured_output: true
                        input_modalities:
                          - text
                          - image
                        output_modalities:
                          - text
                        tools:
                          - function_calling
                          - web_search
                          - file_search
                          - image_generation
                          - code_interpreter
                          - mcp
                        tiers:
                          - name: standard
                            input_price: 2.5
                            output_price: 10
                            cache_read_price: 1.25
                            cache_write_price: null
                            latency_hint: normal
                            price_variants: []
                          - name: priority
                            input_price: 4.25
                            output_price: 17
                            cache_read_price: 2.125
                            cache_write_price: null
                            latency_hint: fast
                            price_variants: []
                        updated_at: '2026-04-18T02:21:03.169710Z'
                        data_policy: no_training
                generated_at: '2026-04-20T02:00:00Z'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/workspaces:
    get:
      operationId: listWorkspaces
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - workspace:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List workspaces
      description: |
        Returns the workspaces accessible to the API key.
        Requires `workspace:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Workspaces
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWorkspaceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: getWorkspace
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - workspace:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get workspace
      description: |
        Returns workspace details.
        Requires `workspace:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Workspaces
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWorkspaceItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateWorkspace
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - workspace:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: workspace.updated
        raw_secret_behavior: none
      summary: Update workspace
      description: >
        Updates workspace metadata.

        API key callers can update `name` only. Requires `workspace:write`
        scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Workspaces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicWorkspaceItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/routing-defaults:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: getRoutingDefaults
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - routing:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get routing defaults
      description: |
        Returns the current routing defaults for a workspace.
        Requires `routing:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Routing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingDefaultsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateRoutingDefaults
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - routing:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: routing_defaults.updated
        raw_secret_behavior: none
      summary: Update routing defaults
      description: >
        Partially updates routing defaults for a workspace.

        Only fields present in the request are changed. Requires `routing:write`
        scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Routing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                optimize:
                  type: string
                  enum:
                    - cost
                    - cost-focus
                    - ttft
                    - ttft-focus
                    - tps
                    - tps-focus
                    - balanced
                data_policy:
                  type: string
                  enum:
                    - none
                    - no_training
                    - zdr
                allow_fallbacks:
                  type: boolean
                max_fallback_attempts:
                  type: integer
                  minimum: 1
                  maximum: 19
                  default: 19
                providers:
                  type: array
                  items:
                    type: string
                exclude_providers:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingDefaultsResponse'
        '202':
          description: Accepted — committed; edge enforcement sync deferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingDefaultsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRoutingDefaults
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - routing:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: routing_defaults.deleted
        raw_secret_behavior: none
      summary: Clear routing defaults
      description: |
        Clears all routing defaults for a workspace.
        Requires `routing:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Routing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingDefaultsResponse'
        '202':
          description: Accepted — committed; edge enforcement sync deferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutingDefaultsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/usage:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getWorkspaceUsage
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - usage:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get workspace usage
      description: |
        Returns aggregated usage metrics for a workspace.
        Requires `usage:read` scope.
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for usage period
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for usage period
        - name: group_by
          in: query
          required: false
          schema:
            type: string
            default: model
          description: Group results by dimension
      security:
        - ApiKeyAuth: []
      tags:
        - Usage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageAggregateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/requests:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listRequests
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - usage:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List requests
      description: |
        Lists request metadata for a workspace.
        Requires `usage:read` scope.
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter by start date
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Filter by end date
        - name: model
          in: query
          required: false
          schema:
            type: string
          description: Filter by model name
        - name: provider
          in: query
          required: false
          schema:
            type: string
          description: Filter by provider
        - name: trace_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by trace ID
        - name: success
          in: query
          required: false
          schema:
            type: boolean
          description: Filter by success status
        - name: api_key_source
          in: query
          required: false
          schema:
            type: string
            enum:
              - platform
              - byok
          description: Filter by API key source
        - name: is_final_attempt
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Filter by final attempt status
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
          description: Maximum number of results
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Offset for pagination
      security:
        - ApiKeyAuth: []
      tags:
        - Usage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/requests/{request_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: request_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getRequest
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - usage:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: request.detail.read
        raw_secret_behavior: none
      summary: Get request detail
      description: |
        Returns metadata for a single request.
        Requires `usage:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Usage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/budgets:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: listBudgets
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - budgets:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List budgets
      description: |
        Returns the budgets for a workspace.
        Requires `budgets:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Budgets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createBudget
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - budgets:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: idempotency_key
        audit_event: budget.created
        raw_secret_behavior: none
      summary: Create budget
      description: >
        Creates a new budget limit for a workspace, API key, or BYOK provider
        scope.

        Requires `budgets:write` scope. Supports `Idempotency-Key` header.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
            pattern: ^[A-Za-z0-9_-]+$
          description: Idempotency key for safe retries
      security:
        - ApiKeyAuth: []
      tags:
        - Budgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBudgetRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetResponse'
        '202':
          description: Accepted — committed; edge enforcement sync deferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetResponse'
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: >-
            Budget already exists for this scope and period, or idempotency
            conflict
        '422':
          description: Validation error
  /v1/workspaces/{workspace_id}/budgets/{budget_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
      - name: budget_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Budget identifier
    get:
      operationId: getBudget
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - budgets:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get budget
      description: |
        Returns a specific budget.
        Requires `budgets:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Budgets
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateBudget
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - budgets:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: budget.updated
        raw_secret_behavior: none
      summary: Update budget
      description: >
        Updates mutable fields of an existing budget (limit, enforce,
        include_byok).

        Requires `budgets:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Budgets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBudgetRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetResponse'
        '202':
          description: Accepted — committed; edge enforcement sync deferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetResponse'
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Validation error
    delete:
      operationId: deleteBudget
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - budgets:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: budget.deleted
        raw_secret_behavior: none
      summary: Delete budget
      description: |
        Deletes a budget limit.
        Requires `budgets:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Budgets
      responses:
        '202':
          description: Accepted — committed; edge enforcement sync deferred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetPropagationPendingResponse'
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/api-keys:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: listApiKeys
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List API keys
      description: |
        Returns API keys for a workspace. Excludes playground keys.
        Requires `keys:read` scope.
      parameters:
        - name: include_revoked
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include revoked keys in the response
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApiKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:write
        scope_mode: all
        rate_limit_class: key_creation
        idempotency: none
        audit_event: api_key.created
        raw_secret_behavior: one_time_return
      summary: Create API key
      description: >
        Creates a new API key for the workspace.

        The full key value is returned only in this response and cannot be
        retrieved again.

        Requires `keys:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyPublicResponse'
        '202':
          description: Accepted — key created, edge propagation queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyPublicResponse'
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/api-keys/{api_key_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: API key identifier
    get:
      operationId: getApiKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get API key
      description: |
        Returns a specific API key's metadata.
        Requires `keys:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiKeyItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateApiKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: api_key.updated
        raw_secret_behavior: none
      summary: Update API key
      description: |
        Updates an API key's metadata or configuration.
        Requires `keys:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateApiKeyResponse'
        '202':
          description: Accepted — changes queued for propagation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateApiKeyResponse'
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: revokeApiKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: api_key.revoked
        raw_secret_behavior: none
      summary: Revoke API key
      description: |
        Revokes an API key. The key cannot be used after revocation.
        Requires `keys:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '202':
          description: Accepted — revocation queued for propagation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropagationPendingResponse'
        '204':
          description: No content — key revoked
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/api-keys/{api_key_id}/usage:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: API key identifier
    get:
      operationId: getApiKeyUsage
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - keys:read
          - usage:read
        scope_mode: any
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get API key usage
      description: |
        Returns usage statistics for a specific API key.
        Requires `keys:read` or `usage:read` scope.
      parameters:
        - name: period
          in: query
          required: false
          schema:
            type: string
            enum:
              - day
              - week
              - month
            default: month
          description: Usage aggregation period
      security:
        - ApiKeyAuth: []
      tags:
        - API Keys
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyUsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/byok/providers:
    get:
      operationId: listByokProviders
      x-stability: preview
      x-auriko-auth:
        credential_types: []
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: discovery
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List BYOK providers
      description: |
        Returns providers that accept bring-your-own-key credentials, with each
        provider's conservative default account tier. Allowed `account_tier`
        values for key creation come from the tiers endpoint.
      security: []
      tags:
        - BYOK
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/byok/providers
      responses:
        '200':
          description: List of BYOK providers
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByokProvidersResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/byok/providers/{provider}/tiers:
    parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
        description: Provider identifier (for example `openai`)
    get:
      operationId: getByokProviderTiers
      x-stability: preview
      x-auriko-auth:
        credential_types: []
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: discovery
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List provider account tiers
      description: |
        Returns the allowed `account_tier` values for a BYOK provider.
        Auriko derives each key's data policy from provider + tier —
        callers never submit a data policy directly.
      security: []
      tags:
        - BYOK
      responses:
        '200':
          description: Tier options for the provider
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByokProviderTiersResponse'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
  /v1/workspaces/{workspace_id}/byok-keys:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: listByokKeys
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - byok:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List BYOK keys
      description: |
        Returns the workspace's BYOK keys as redacted metadata (masked key
        prefix only). Provider secrets are never returned by any endpoint.
        Requires `byok:read` scope.
      parameters:
        - name: provider
          in: query
          required: false
          schema:
            type: string
          description: Filter by provider identifier
      security:
        - ApiKeyAuth: []
      tags:
        - BYOK
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListByokKeysResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createByokKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - byok:write
        scope_mode: all
        rate_limit_class: mgmt_byok_writes
        idempotency: idempotency_key
        audit_event: byok_key.created
        raw_secret_behavior: none
      summary: Create BYOK key
      description: |
        Creates a BYOK key with create-time admission validation: the
        submitted secret is verified against the provider before activation.
        Invalid credentials are rejected and nothing is saved; transient
        validation failures return a retryable `502` and nothing is saved.

        The secret is write-only — accepted once here, encrypted at rest, and
        never returned by any endpoint. `Idempotency-Key` replays return the
        redacted metadata response only, never the secret.

        `account_tier` accepts the values published by the tiers endpoint;
        when omitted, Auriko auto-detects the tier where the provider exposes
        reliable signals and otherwise uses the provider's conservative
        default. Auriko derives the key's data policy from provider + tier.

        May return `202` with `propagation_status: "pending"` when the change
        is committed but edge routing propagation is still being applied.
        Requires `byok:write` scope.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
            pattern: ^[A-Za-z0-9_-]+$
          description: Idempotency key for safe retries
      security:
        - ApiKeyAuth: []
      tags:
        - BYOK
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateByokKeyRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicByokKeyItem'
        '202':
          description: Created — edge propagation pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicByokKeyItem'
        '400':
          description: Invalid parameter value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Idempotency-Key conflict
        '422':
          description: Validation error
        '502':
          description: Provider validation did not complete — retry the request
  /v1/workspaces/{workspace_id}/byok-keys/{byok_key_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
      - name: byok_key_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: BYOK key identifier
    get:
      operationId: getByokKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - byok:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get BYOK key
      description: |
        Returns a BYOK key's redacted metadata. The provider secret is never
        returned. Requires `byok:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - BYOK
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicByokKeyItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateByokKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - byok:write
        scope_mode: all
        rate_limit_class: mgmt_byok_writes
        idempotency: naturally_idempotent
        audit_event: byok_key.updated
        raw_secret_behavior: none
      summary: Update BYOK key
      description: |
        Updates safe metadata and routing-affecting state: `name`,
        `is_default`, `account_tier`, and `disabled`. The provider secret is
        immutable and secret fields are rejected — to replace a secret, create
        a new key, set it as default, then delete the old key.

        May return `202` with `propagation_status: "pending"` when the change
        is committed but edge routing propagation is still being applied.
        Requires `byok:write` scope.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateByokKeyRequest'
      security:
        - ApiKeyAuth: []
      tags:
        - BYOK
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicByokKeyItem'
        '202':
          description: Accepted — changes queued for propagation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicByokKeyItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: State conflict — for example, setting a disabled key as default
    delete:
      operationId: deleteByokKey
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - byok:write
        scope_mode: all
        rate_limit_class: mgmt_byok_writes
        idempotency: naturally_idempotent
        audit_event: byok_key.deleted
        raw_secret_behavior: none
      summary: Delete BYOK key
      description: |
        Deletes a BYOK key. If the key was the provider's default, edge
        routing stops using it within the propagation window; may return
        `202` with `propagation_status: "pending"` while propagation applies.
        Requires `byok:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - BYOK
      responses:
        '202':
          description: Accepted — deletion queued for propagation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ByokPropagationPendingResponse'
        '204':
          description: No content — key deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/workspaces/{workspace_id}/billing/balance:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace identifier
    get:
      operationId: getCreditBalance
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - billing:read
        scope_mode: all
        rate_limit_class: mgmt_billing_reads
        idempotency: naturally_idempotent
        audit_event: billing.balance.read
        raw_secret_behavior: none
      summary: Get credit balance
      description: |
        Returns the workspace credit balance, tier, and billing configuration.
        Requires `billing:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Billing
      x-codeSamples:
        - lang: bash
          label: curl
          source: >
            curl
            https://api.auriko.ai/v1/workspaces/550e8400-e29b-41d4-a716-446655440000/billing/balance
            \
              -H "Authorization: Bearer $AURIKO_API_KEY"
      responses:
        '200':
          description: Credit balance and billing details
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceResponse'
              example:
                balance_microdollars: 4850000
                balance_cents: 4850
                balance_dollars: '48.50'
                lifetime_purchased_microdollars: 10000000
                lifetime_purchased_cents: 10000
                lifetime_used_microdollars: 5150000
                lifetime_used_cents: 5150
                auto_reload_enabled: false
                has_payment_method: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
  /v1/workspaces/{workspace_id}/billing/purchases:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listBillingPurchases
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - billing:read
        scope_mode: all
        rate_limit_class: mgmt_billing_reads
        idempotency: naturally_idempotent
        audit_event: billing.purchases.read
        raw_secret_behavior: none
      summary: List billing purchases
      description: |
        Returns credit purchase history for a workspace.
        Requires `billing:read` scope.
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
          description: Maximum number of results
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Offset for pagination
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - completed
              - failed
              - refunded
          description: Filter by purchase status
        - name: purchase_type
          in: query
          required: false
          schema:
            type: string
            enum:
              - manual
              - auto_reload
          description: Filter by purchase type
      security:
        - ApiKeyAuth: []
      tags:
        - Billing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
  /v1/workspaces/{workspace_id}/billing/usage:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getBillingUsage
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - billing:read
        scope_mode: all
        rate_limit_class: mgmt_billing_reads
        idempotency: naturally_idempotent
        audit_event: billing.usage.read
        raw_secret_behavior: none
      summary: Get billing usage
      description: |
        Returns billing usage summary for a workspace.
        Requires `billing:read` scope.
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: Start date for usage period
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: End date for usage period
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Maximum number of results
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: Offset for pagination
      security:
        - ApiKeyAuth: []
      tags:
        - Billing
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/GatewayUnavailable'
  /v1/workspaces/{workspace_id}/billing/auto-reload:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getAutoReloadSettings
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - billing:read
        scope_mode: all
        rate_limit_class: mgmt_billing_reads
        idempotency: naturally_idempotent
        audit_event: billing.auto_reload.read
        raw_secret_behavior: none
      summary: Get auto-reload settings
      description: >
        Returns auto-reload configuration for a workspace.

        API-key callers receive a `payment_method_configured` boolean instead of
        card details.

        Requires `billing:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Billing
      responses:
        '200':
          description: Auto-reload settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                  threshold_cents:
                    type: integer
                  threshold_dollars:
                    type: number
                  amount_cents:
                    type: integer
                  amount_dollars:
                    type: number
                  payment_method_configured:
                    type: boolean
                  failed_count:
                    type: integer
                  disabled_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/billing/subscription:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: getSubscriptionStatus
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - billing:read
        scope_mode: all
        rate_limit_class: mgmt_billing_reads
        idempotency: naturally_idempotent
        audit_event: billing.subscription.read
        raw_secret_behavior: none
      summary: Get subscription status
      description: |
        Returns tier, subscription status, and period information.
        Does not trigger Stripe reconciliation.
        Requires `billing:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Billing
      responses:
        '200':
          description: Subscription status
          content:
            application/json:
              schema:
                type: object
                properties:
                  tier:
                    type: string
                  subscription_status:
                    type: string
                  subscription_current_period_end:
                    type:
                      - string
                      - 'null'
                    format: date-time
                  cancel_at_period_end:
                    type: boolean
                  subscription_cancel_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
                  trial_expires_at:
                    type:
                      - string
                      - 'null'
                    format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/members:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listMembers
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - members:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List workspace members
      description: |
        Returns workspace members with role and profile info.
        Requires `members:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Members
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum members to return (1-100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of members to skip for pagination
      responses:
        '200':
          description: Workspace members list
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        user_id:
                          type: string
                        role:
                          type: string
                        joined_at:
                          type: string
                          format: date-time
                        display_name:
                          type:
                            - string
                            - 'null'
                        email:
                          type:
                            - string
                            - 'null'
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/workspaces/{workspace_id}/invites:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listInvites
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - members:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: List workspace invites
      description: |
        Returns pending and expired invitations.
        Requires `members:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Members
      parameters:
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum invites to return (1-100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of invites to skip for pagination
      responses:
        '200':
          description: Workspace invites list
          content:
            application/json:
              schema:
                type: object
                properties:
                  invites:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        email:
                          type: string
                        role:
                          type: string
                        status:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        expires_at:
                          type: string
                          format: date-time
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createInvite
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - invites:write
        scope_mode: all
        rate_limit_class: mgmt_invites
        idempotency: idempotency_key
        audit_event: invite.created
        raw_secret_behavior: none
      summary: Create workspace invite
      description: |
        Sends a workspace invitation email.
        API-key callers can only create member-role invites.
        Requires `invites:write` scope. Supports `Idempotency-Key` header.
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          schema:
            type: string
            maxLength: 255
            pattern: ^[A-Za-z0-9_-]+$
          description: Idempotency key for safe retries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to invite
                role:
                  type: string
                  enum:
                    - admin
                    - member
                  default: member
                  description: Role for the invited member
      security:
        - ApiKeyAuth: []
      tags:
        - Members
      responses:
        '201':
          description: Invite created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  email:
                    type: string
                  role:
                    type: string
                  status:
                    type: string
                  created_at:
                    type: string
                    format: date-time
                  expires_at:
                    type: string
                    format: date-time
                  email_sent:
                    type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          description: Idempotency-Key conflict
  /v1/workspaces/{workspace_id}/invites/{invite_id}:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: invite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      operationId: cancelInvite
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - invites:write
        scope_mode: all
        rate_limit_class: management_writes
        idempotency: naturally_idempotent
        audit_event: invite.cancelled
        raw_secret_behavior: none
      summary: Cancel workspace invite
      description: |
        Cancels a pending invitation.
        Requires `invites:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Members
      responses:
        '200':
          description: Invite cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Invite is not in a cancellable state
  /v1/workspaces/{workspace_id}/invites/{invite_id}/resend:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: invite_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      operationId: resendInvite
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - invites:write
        scope_mode: all
        rate_limit_class: mgmt_invites
        idempotency: naturally_idempotent
        audit_event: invite.resent
        raw_secret_behavior: none
      summary: Resend workspace invite
      description: |
        Resends an invitation with a new token.
        API-key callers can only resend member-role invites.
        Requires `invites:write` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Members
      responses:
        '200':
          description: Invite resent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Invite is not in a resendable state
  /v1/workspaces/{workspace_id}/audit/events:
    parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      operationId: listAuditEvents
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes:
          - audit:read
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: audit.events.read
        raw_secret_behavior: none
      summary: List audit events
      description: |
        Returns workspace management audit history.
        Supports filtering by time range, actor, action, and target.
        Requires `audit:read` scope.
      security:
        - ApiKeyAuth: []
      tags:
        - Audit
      parameters:
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter events from this timestamp (inclusive)
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Filter events up to this timestamp (inclusive)
        - name: actor_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by actor type
        - name: action
          in: query
          required: false
          schema:
            type: string
          description: Filter by action
        - name: target_type
          in: query
          required: false
          schema:
            type: string
          description: Filter by target type
        - name: target_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by target ID
        - name: request_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by request ID
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          description: Maximum events to return (1-100)
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of events to skip for pagination
      responses:
        '200':
          description: Audit events list
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        actor_type:
                          type: string
                        actor_id:
                          type: string
                        actor_display:
                          type: string
                        action:
                          type: string
                        target_type:
                          type: string
                        target_id:
                          type:
                            - string
                            - 'null'
                        metadata:
                          type: object
                        request_id:
                          type:
                            - string
                            - 'null'
                        created_at:
                          type: string
                          format: date-time
                  total:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /v1/me:
    get:
      operationId: getApiKeyIdentity
      x-stability: preview
      x-auriko-auth:
        credential_types:
          - api_key
        api_key_scopes: []
        scope_mode: all
        rate_limit_class: management_reads
        idempotency: naturally_idempotent
        audit_event: null
        raw_secret_behavior: none
      summary: Get API key identity
      description: |
        Returns database-fresh credential introspection for the calling API key:
        credential type, status, derived profile, key metadata, workspace,
        granted scopes, structured rate limits, and expiry. Any valid active
        API key may call this endpoint — no scope is required.
      tags:
        - Account
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: bash
          label: curl
          source: |
            curl https://api.auriko.ai/v1/me \
              -H "Authorization: Bearer $AURIKO_API_KEY"
        - lang: python
          label: Python
          source: >
            from auriko import Client


            client = Client()

            identity = client.me.get()

            print(f"Workspace: {identity.workspace.id}, Profile:
            {identity.profile}")
        - lang: typescript
          label: TypeScript
          source: >
            import { Client } from "@auriko/sdk";


            const client = new Client();

            const identity = await client.me.get();

            console.log(`Workspace: ${identity.workspace.id}, Profile:
            ${identity.profile}`);
      responses:
        '200':
          description: API key identity
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            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/ApiKeyIdentity'
              example:
                credential_type: api_key
                status: active
                profile: inference
                key_id: 550e8400-e29b-41d4-a716-446655440000
                key_prefix: ak_live_abc1
                key_name: Production inference
                workspace:
                  id: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
                  name: Acme Corp
                scopes:
                  - inference:invoke
                rate_limits:
                  inference_rpm: 1000
                  management_reads_rpm: 120
                  management_writes_rpm: 30
                expires_at: null
                created_at: '2026-01-15T00:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/messages:
    post:
      operationId: createMessage
      x-stability: stable
      summary: Create a message (Anthropic format)
      description: >
        Creates a model response using the Anthropic Messages API format.


        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)

        using Anthropic's native event types: `message_start`,
        `content_block_start`,

        `content_block_delta`, `content_block_stop`, `message_delta`,
        `message_stop`.


        A terminal `auriko_metadata` event delivers routing metadata (Auriko
        extension).


        ## Extended Thinking


        Use the `thinking` parameter to enable extended thinking. Response will

        include `thinking` and optionally `redacted_thinking` content blocks.


        ## Multi-Model Routing


        Use `gateway.models[]` instead of `model` to enable multi-model routing.
      security:
        - ApiKeyAuth: []
      tags:
        - Messages
      parameters:
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
          description: Anthropic API version (passed upstream)
          example: '2023-06-01'
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
          description: |
            Comma-separated list of beta features to enable.
            Example: "extended-thinking-2025-04-11"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
            examples:
              basic:
                summary: Basic message
                value:
                  model: claude-sonnet-4-20250514
                  max_tokens: 1024
                  messages:
                    - role: user
                      content: What is the capital of France?
              with_thinking:
                summary: With extended thinking
                value:
                  model: claude-sonnet-4-20250514
                  max_tokens: 16000
                  thinking:
                    type: enabled
                    budget_tokens: 10000
                  messages:
                    - role: user
                      content: 'Solve this step by step: what is 127 * 389?'
      responses:
        '200':
          description: |
            Successful message response.

            For streaming (`stream: true`), responses use Anthropic SSE format:
            `event: <type>\ndata: <json>\n\n`

            Event types: `message_start`, `ping`, `content_block_start`,
            `content_block_delta` (with delta types: `thinking_delta`,
            `signature_delta`, `text_delta`, `input_json_delta`),
            `content_block_stop`, `message_delta`, `message_stop`.

            A terminal `event: auriko_metadata` delivers routing metadata.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnthropicResponse'
              example:
                id: msg_01XFDUDYJgAACzvnptvVoYEL
                type: message
                role: assistant
                content:
                  - type: text
                    text: The capital of France is Paris.
                model: claude-sonnet-4-20250514
                stop_reason: end_turn
                stop_sequence: null
                usage:
                  input_tokens: 14
                  output_tokens: 10
            text/event-stream:
              schema:
                type: string
                description: |
                  Anthropic SSE event stream. Each event has the format:
                  `event: <type>\ndata: <json>\n\n`
        '400':
          $ref: '#/components/responses/AnthropicBadRequest'
        '401':
          $ref: '#/components/responses/AnthropicUnauthorized'
        '429':
          $ref: '#/components/responses/AnthropicRateLimit'
        '500':
          $ref: '#/components/responses/AnthropicInternalError'
        '503':
          $ref: '#/components/responses/AnthropicServiceUnavailable'
  /v1/messages/count_tokens:
    post:
      operationId: countTokens
      x-stability: stable
      summary: Count tokens (Anthropic format)
      description: |
        Counts the number of tokens in a message payload without generating
        a response. Uses the Anthropic Messages API format.

        Token counts for non-Claude models use a reference tokenizer. When
        this occurs, the response includes an `X-Token-Count-Model` header
        indicating the model used for counting.

        Only `gateway.routing` is allowed. Other gateway keys return 400.
      security:
        - ApiKeyAuth: []
      tags:
        - Messages
      parameters:
        - name: anthropic-version
          in: header
          required: false
          schema:
            type: string
          description: Anthropic API version (defaults to 2023-06-01)
          example: '2023-06-01'
        - name: anthropic-beta
          in: header
          required: false
          schema:
            type: string
          description: Comma-separated beta features
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CountTokensRequest'
            example:
              model: claude-sonnet-4-20250514
              messages:
                - role: user
                  content: How many tokens is this?
      responses:
        '200':
          description: Token count result
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            X-Token-Count-Model:
              $ref: '#/components/headers/X-Token-Count-Model'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountTokensResponse'
              example:
                input_tokens: 12
        '400':
          $ref: '#/components/responses/AnthropicBadRequest'
        '401':
          $ref: '#/components/responses/AnthropicUnauthorized'
        '429':
          $ref: '#/components/responses/AnthropicRateLimit'
        '500':
          $ref: '#/components/responses/AnthropicInternalError'
        '503':
          $ref: '#/components/responses/AnthropicServiceUnavailable'
components:
  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'
    X-Token-Count-Model:
      description: >
        Model used for token counting when a different model was used.

        Only present on /v1/messages/count_tokens responses for non-Claude
        models.
      schema:
        type: string
      example: claude-haiku-4-5-20251001
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication.
        Keys start with `ak_` prefix.
        Example: `Authorization: Bearer ak_live_xxxxxxxxxxxx`
  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
    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
    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
    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
    Forbidden:
      description: You do not have permission to perform this action
      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: You do not have permission to perform this action.
              type: permission_error
              param: null
              code: insufficient_permissions
    NotFound:
      description: Resource 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: The requested resource was not found.
              type: not_found_error
              param: null
              code: resource_not_found
    GatewayUnavailable:
      description: |
        API gateway is temporarily unavailable.
      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
          schema:
            type: integer
          required: false
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              message: Gateway is temporarily unavailable. Retry in a few seconds.
              type: api_error
              param: null
              code: upstream_error
    AnthropicBadRequest:
      description: Bad request - invalid parameters (Anthropic format)
      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/AnthropicErrorResponse'
          example:
            type: error
            error:
              type: invalid_request_error
              message: 'Missing required parameter: ''max_tokens''.'
    AnthropicUnauthorized:
      description: Authentication failed (Anthropic format)
      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/AnthropicErrorResponse'
          example:
            type: error
            error:
              type: authentication_error
              message: API key is invalid.
    AnthropicRateLimit:
      description: Rate limit exceeded (Anthropic format)
      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
          schema:
            type: integer
          example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnthropicErrorResponse'
          example:
            type: error
            error:
              type: rate_limit_error
              message: Rate limit exceeded. Retry after 60 seconds.
    AnthropicInternalError:
      description: Internal server error (Anthropic format)
      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/AnthropicErrorResponse'
          example:
            type: error
            error:
              type: api_error
              message: An unexpected error occurred.
    AnthropicServiceUnavailable:
      description: Service unavailable (Anthropic format)
      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
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnthropicErrorResponse'
          example:
            type: error
            error:
              type: overloaded_error
              message: Service is temporarily unavailable.
  schemas:
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    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.
    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: '#/components/schemas/SystemMessage'
          user: '#/components/schemas/UserMessage'
          assistant: '#/components/schemas/AssistantMessage'
          tool: '#/components/schemas/ToolMessage'
          developer: '#/components/schemas/DeveloperMessage'
          function: '#/components/schemas/FunctionMessage'
    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
    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
    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
    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
    Tool:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          const: function
        function:
          $ref: '#/components/schemas/FunctionDefinition'
    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
    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.
    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)
    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
    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
    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'
    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
    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
    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'
    PromptTokensDetails:
      type: object
      description: Detailed breakdown of prompt tokens
      properties:
        cached_tokens:
          type: integer
          description: Tokens served from cache
        cache_write_tokens:
          type: integer
          description: >-
            Tokens written to prompt cache. Provider-dependent: present when the
            upstream provider reports cache write details, absent otherwise.
    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).
    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.
    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
    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.
    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'
    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'
    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.
    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).
    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
    ModelList:
      type: object
      description: List of available models with Auriko extensions
      required:
        - object
        - data
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        catalog_version:
          type: string
          description: Version of the model catalog
        catalog_age_seconds:
          type: number
          description: Age of catalog in seconds
    Model:
      type: object
      description: Model information with provider availability
      required:
        - id
        - object
        - created
        - owned_by
      properties:
        id:
          type: string
          description: Canonical model ID
        object:
          type: string
          const: model
        created:
          type: integer
          description: Unix timestamp
        owned_by:
          type: string
          description: Always "auriko"
        context_window:
          type: integer
          description: >
            Auriko extension: Largest context window across the model's
            providers.
        supported_endpoints:
          type: array
          description: >
            Auriko extension: APIs the model supports (e.g., `chat_completions`,
            `responses`, `batch`).
          items:
            type: string
        providers:
          type: array
          description: |
            Auriko extension: Available providers with pricing.

            Allows clients to see all available options for this model.
          items:
            $ref: '#/components/schemas/ModelProvider'
    ModelProvider:
      type: object
      description: Provider offering for a model
      required:
        - name
        - input_price
        - output_price
      properties:
        name:
          type: string
          description: Provider identifier
        input_price:
          type: number
          description: Input price per 1M tokens (USD)
        output_price:
          type: number
          description: Output price per 1M tokens (USD)
        data_policy:
          type: string
          enum:
            - none
            - no_training
            - zdr
          description: Provider data retention policy
    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
    ProviderResponse:
      type: object
      description: A provider represented in Auriko model catalog entries
      required:
        - id
        - display_name
        - description
        - icon
        - data_policy
      properties:
        id:
          type: string
          description: Canonical provider ID (snake_case)
          example: openai
        display_name:
          type: string
          description: Human-readable provider name
          example: OpenAI
        description:
          type: string
          description: Brief description of the provider
          example: GPT-4o, o1, and more
        icon:
          type: string
          description: Provider icon identifier
          example: openai
        data_policy:
          type: string
          enum:
            - none
            - no_training
            - zdr
          description: Provider data retention policy
          example: no_training
    ProvidersListResponse:
      type: object
      required:
        - providers
        - count
      properties:
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderResponse'
        count:
          type: integer
          description: Total number of providers
    CanonicalModelResponse:
      type: object
      description: A canonical model with provider availability
      required:
        - id
        - family
        - display_name
        - capabilities
        - input_modalities
        - output_modalities
        - providers
        - has_free_provider
      properties:
        id:
          type: string
          description: Canonical model ID (lowercase-hyphenated)
          example: gpt-4o
        family:
          type: string
          description: Model family
          example: gpt-4o
        display_name:
          type: string
          description: Human-readable model name
          example: GPT-4o
        capabilities:
          type: object
          additionalProperties:
            type: boolean
          description: >
            Capability flags for this model. A true value means at least one
            routable provider supports this capability. For per-provider truth,
            use /v1/directory/models.
          example:
            supports_tools: true
            supports_reasoning: false
            supports_streaming: true
        input_modalities:
          type: array
          items:
            type: string
          description: |
            Union of input modalities across all routable providers.
          example:
            - text
            - image
        output_modalities:
          type: array
          items:
            type: string
          description: |
            Union of output modalities across all routable providers.
          example:
            - text
        author:
          type:
            - string
            - 'null'
          description: Model author/creator
          example: openai
        providers:
          type: array
          items:
            type: string
          description: Provider IDs offering this model
          example:
            - openai
            - fireworks_ai
            - together_ai
        has_free_provider:
          type: boolean
          description: Whether at least one provider offers this model for free
    ModelsListResponse:
      type: object
      required:
        - models
        - count
      properties:
        models:
          type: array
          items:
            $ref: '#/components/schemas/CanonicalModelResponse'
        count:
          type: integer
          description: Total number of models
        playground_defaults:
          type: array
          items:
            type: string
          description: >-
            Ordered list of model IDs recommended as playground defaults.
            Frontend should select the first available.
    DirectoryResponse:
      type: object
      description: Model directory with detailed provider route information
      required:
        - models
        - generated_at
      properties:
        models:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelEntry'
          description: Map of canonical model ID to model entry
        generated_at:
          type: string
          description: ISO 8601 timestamp when the directory was generated
          example: '2026-03-17T12:00:00Z'
    ModelEntry:
      type: object
      description: A model entry in the directory
      required:
        - family
        - display_name
        - providers
      properties:
        family:
          type: string
          description: Model family
        author:
          type:
            - string
            - 'null'
          description: Model author
        display_name:
          type: string
          description: Human-readable model name
        providers:
          type: array
          items:
            $ref: '#/components/schemas/ProviderEntry'
        supported_parameters:
          type: array
          items:
            type: string
          description: |
            Union of supported_parameters across all providers for this model.
        aliases:
          type: array
          items:
            type: string
          description: >
            Identifiers that resolve to this model (official undated names and
            provider redirects), sorted. Empty if none.
    ProviderEntry:
      type: object
      description: Provider details for a model in the directory
      required:
        - provider
        - provider_model_id
      properties:
        provider:
          type: string
          description: Provider identifier
        provider_model_id:
          type: string
          description: Provider-specific model ID
        context_window:
          type:
            - integer
            - 'null'
          description: Maximum context window in tokens
        max_output_tokens:
          type:
            - integer
            - 'null'
          description: Maximum output tokens
        capabilities:
          type: object
          additionalProperties:
            type: boolean
          description: >-
            Provider capabilities for this model (e.g., function_calling,
            vision)
        input_modalities:
          type: array
          items:
            type: string
          description: Supported input modalities (text, image, audio, etc.)
        output_modalities:
          type: array
          items:
            type: string
          description: Supported output modalities
        tools:
          type: array
          items:
            type: string
          description: Supported tool types
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/TierEntry'
          description: Pricing tiers available
        updated_at:
          type:
            - string
            - 'null'
          description: When this provider entry was last updated
        data_policy:
          type:
            - string
            - 'null'
          enum:
            - none
            - no_training
            - zdr
            - null
          description: Provider data retention policy
        accepted_params:
          type:
            - array
            - 'null'
          items:
            type: string
          description: >
            Optional parameters this offering accepts (e.g., temperature, seed).
            Null if not yet populated.
        supported_parameters:
          type: array
          items:
            type: string
          description: |
            All parameters this offering supports.
        supported_endpoints:
          type: array
          items:
            type: string
          description: >
            API endpoints this offering supports (e.g., chat_completions,
            responses).
    TierEntry:
      type: object
      description: A pricing tier for a provider-model combination
      required:
        - name
      properties:
        name:
          type: string
          description: Tier name (e.g., standard, flex)
          example: standard
        input_price:
          type:
            - number
            - 'null'
          description: USD per million input tokens
          example: 2.5
        output_price:
          type:
            - number
            - 'null'
          description: USD per million output tokens
          example: 10
        cache_read_price:
          type:
            - number
            - 'null'
          description: USD per million cached input tokens (read)
          example: 1.25
        cache_write_price:
          type:
            - number
            - 'null'
          description: USD per million cached input tokens (write)
          example: 3.75
        latency_hint:
          type:
            - string
            - 'null'
          description: Expected latency (fast, normal, slow)
          example: fast
        price_variants:
          type: array
          items:
            $ref: '#/components/schemas/PriceVariantEntry'
          description: >-
            Context-dependent price overrides (long context, audio modality,
            etc.)
    PriceVariantEntry:
      type: object
      description: Context-dependent price override (e.g., long-context surcharge)
      required:
        - role
        - price
        - constraints
      properties:
        role:
          type: string
          description: 'Price role: input, output, cache_read, cache_write'
          example: input
        price:
          type: number
          description: USD per million tokens when constraints match
          example: 5
        constraints:
          type: object
          additionalProperties:
            type: string
          description: Conditions that trigger this price
          example:
            context_length: '>128k'
        description:
          type:
            - string
            - 'null'
          description: Human-readable explanation
          example: Long-context surcharge for inputs over 128k tokens
    CreditBalanceResponse:
      type: object
      required:
        - balance_microdollars
        - balance_cents
        - balance_dollars
        - lifetime_purchased_microdollars
        - lifetime_purchased_cents
        - lifetime_used_microdollars
        - lifetime_used_cents
        - auto_reload_enabled
        - has_payment_method
      properties:
        balance_microdollars:
          type: integer
          description: Current balance in microdollars (1 USD = 1,000,000 μ$)
        balance_cents:
          type: integer
          description: Current balance in cents (computed)
        balance_dollars:
          type: string
          description: Current balance in dollars (computed, string for precision)
          example: '48.50'
        lifetime_purchased_microdollars:
          type: integer
          description: Total credits ever purchased in microdollars
        lifetime_purchased_cents:
          type: integer
          description: Total credits ever purchased in cents (computed)
        lifetime_used_microdollars:
          type: integer
          description: Total credits ever consumed in microdollars
        lifetime_used_cents:
          type: integer
          description: Total credits ever consumed in cents (computed)
        auto_reload_enabled:
          type: boolean
          description: Whether auto-reload is enabled
        auto_reload_threshold_microdollars:
          type:
            - integer
            - 'null'
          description: Balance threshold triggering auto-reload
        auto_reload_threshold_cents:
          type:
            - integer
            - 'null'
          description: Balance threshold in cents (computed)
        auto_reload_amount_microdollars:
          type:
            - integer
            - 'null'
          description: Target balance amount for auto-reload
        auto_reload_amount_cents:
          type:
            - integer
            - 'null'
          description: Target balance amount in cents (computed)
        byok_monthly_cap:
          type:
            - integer
            - 'null'
          description: Monthly BYOK request cap (null if unlimited)
        byok_monthly_remaining:
          type:
            - integer
            - 'null'
          description: Remaining BYOK requests this month
        has_payment_method:
          type: boolean
          description: Whether a payment method is on file
    ApiKeyIdentity:
      type: object
      required:
        - credential_type
        - status
        - profile
        - key_id
        - key_prefix
        - key_name
        - workspace
        - scopes
        - rate_limits
        - expires_at
        - created_at
      properties:
        credential_type:
          type: string
          enum:
            - api_key
          description: The authentication scheme used by the caller.
        status:
          type: string
          enum:
            - active
          description: >
            Always "active" on success — disabled or expired keys fail
            authentication with 401 before this response is produced.
        profile:
          type: string
          enum:
            - inference
            - management
            - mixed
          description: Capability class derived server-side from the key's scopes.
        key_id:
          type: string
          format: uuid
          description: The API key's resource ID (not a secret).
        key_prefix:
          type: string
          description: The key's display prefix (e.g. "ak_live_abc1").
        key_name:
          type: string
          description: Human-readable key name.
        workspace:
          type: object
          required:
            - id
            - name
          properties:
            id:
              type: string
              format: uuid
            name:
              type: string
          description: The workspace this key is scoped to.
        scopes:
          type: array
          items:
            type: string
          description: Granted scopes for fine-grained capability decisions.
        rate_limits:
          type: object
          required:
            - inference_rpm
            - management_reads_rpm
            - management_writes_rpm
          properties:
            inference_rpm:
              type: integer
              description: >-
                Requests per minute on inference endpoints (key override or tier
                default).
            management_reads_rpm:
              type: integer
              description: Requests per minute on management read endpoints.
            management_writes_rpm:
              type: integer
              description: Requests per minute on management write endpoints.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Key expiry, or null if the key does not expire.
        created_at:
          type: string
          format: date-time
    ApiKeyBudget:
      type: object
      description: Budget configuration for an API key.
      properties:
        period:
          type: string
          enum:
            - daily
            - weekly
            - monthly
          description: Budget reset period
        limit_usd:
          type: number
          format: double
          minimum: 0.01
          maximum: 1000000
          description: >-
            Spend limit in USD (minimum $0.01, maximum $1,000,000, max 2 decimal
            places)
        enforce:
          type: boolean
          description: Whether to block requests when budget is exceeded
        include_byok:
          type: boolean
          description: Whether BYOK usage counts toward the budget
    PublicApiKeyItem:
      type: object
      description: API key metadata (excludes the secret key value).
      required:
        - id
        - workspace_id
        - name
        - key_prefix
        - profile
        - scopes
        - is_active
        - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the API key
        workspace_id:
          type: string
          format: uuid
          description: Workspace this key belongs to
        name:
          type: string
          description: Human-readable name for the key
        key_prefix:
          type: string
          description: Key prefix for identification (e.g. "ak_live_abcdefgh")
        profile:
          type: string
          enum:
            - inference
            - management
            - mixed
          description: Key profile derived from granted scopes
        scopes:
          type: array
          items:
            type: string
          description: Granted permission scopes
        is_active:
          type: boolean
          description: Whether the key is currently active
        rate_limit_rpm:
          type:
            - integer
            - 'null'
          description: >-
            Per-key rate limit in requests per minute (null inherits workspace
            default)
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Expiration timestamp (null means no expiration)
        created_at:
          type: string
          format: date-time
          description: When the key was created
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the key was last used (null if never used)
        created_by_key_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            ID of the API key that created this key (null if created via
            dashboard)
    CreateBudgetRequest:
      type: object
      additionalProperties: false
      required:
        - scope_type
        - period
        - limit_usd
      properties:
        scope_type:
          type: string
          enum:
            - workspace
            - api_key
            - byok_provider
          description: Budget target class
        scope_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Required for api_key scope (the target key ID in the same workspace)
        scope_provider:
          type:
            - string
            - 'null'
          description: Required for byok_provider scope (e.g., "openai", "anthropic")
        period:
          type: string
          enum:
            - monthly
            - weekly
            - daily
          description: Budget period
        limit_usd:
          type: number
          minimum: 0.01
          maximum: 1000000
          description: Spend limit in USD (max 2 decimal places)
        enforce:
          type: boolean
          default: true
          description: >-
            Whether to enforce the budget at the edge (block requests when
            exhausted)
        include_byok:
          type: boolean
          default: false
          description: >-
            Include BYOK-attributed spend in budget calculation (workspace and
            api_key scopes only)
    UpdateBudgetRequest:
      type: object
      additionalProperties: false
      properties:
        limit_usd:
          type: number
          minimum: 0.01
          maximum: 1000000
          description: Updated spend limit in USD
        enforce:
          type: boolean
          description: Updated enforcement setting
        include_byok:
          type: boolean
          description: Updated BYOK inclusion setting
    BudgetResponse:
      type: object
      description: A budget with derived spend for its current period.
      required:
        - id
        - workspace_id
        - scope_type
        - period
        - limit_usd
        - enforce
        - include_byok
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the budget
        workspace_id:
          type: string
          format: uuid
          description: Workspace this budget belongs to
        scope_type:
          type: string
          enum:
            - workspace
            - api_key
            - byok_provider
          description: What the budget applies to
        scope_id:
          type:
            - string
            - 'null'
          description: API key id for `api_key` scope (null otherwise)
        scope_provider:
          type:
            - string
            - 'null'
          description: Provider identifier for `byok_provider` scope (null otherwise)
        period:
          type: string
          enum:
            - daily
            - weekly
            - monthly
          description: Budget reset period
        limit_usd:
          type: number
          format: double
          description: Spend limit in USD
        enforce:
          type: boolean
          description: Whether requests are blocked when the budget is exceeded
        include_byok:
          type: boolean
          description: Whether BYOK usage counts toward the budget
        created_by:
          type:
            - string
            - 'null'
          description: Identifier of the principal that created the budget
        created_at:
          type: string
          format: date-time
          description: When the budget was created
        updated_at:
          type: string
          format: date-time
          description: When the budget was last updated
        spend_microdollars:
          type: integer
          description: Spend in the current period, in microdollars
        spend_usd:
          type: number
          format: double
          description: Spend in the current period, in USD
        percent_used:
          type: number
          format: double
          description: Fraction of the limit consumed in the current period
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: >-
            "pending" when the change committed but the edge-KV sync did not
            complete immediately; the edge converges on its next read.
            Absent/null otherwise.
    BudgetPropagationPendingResponse:
      type: object
      description: >-
        Response when a budget deletion is committed but edge propagation is
        pending.
      required:
        - id
        - propagation_status
        - message
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the affected budget
        propagation_status:
          type: string
          enum:
            - pending
          description: Propagation status
        message:
          type: string
          description: Human-readable status message
    RoutingDefaultsModel:
      type: object
      description: Workspace routing defaults applied when a request omits a routing field.
      properties:
        optimize:
          type:
            - string
            - 'null'
          enum:
            - cost
            - cost-focus
            - ttft
            - ttft-focus
            - tps
            - tps-focus
            - balanced
            - null
          description: Default optimization target
        data_policy:
          type:
            - string
            - 'null'
          enum:
            - none
            - no_training
            - zdr
            - null
          description: Default data policy
        allow_fallbacks:
          type:
            - boolean
            - 'null'
          description: Whether fallback providers are allowed by default
        max_fallback_attempts:
          type:
            - integer
            - 'null'
          description: Default maximum number of fallback attempts
        providers:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Default provider allowlist
        exclude_providers:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Default provider denylist
    RoutingDefaultsResponse:
      type: object
      description: Workspace routing defaults with optional propagation status.
      required:
        - workspace_id
      properties:
        workspace_id:
          type: string
          format: uuid
          description: Workspace these defaults belong to
        routing_defaults:
          oneOf:
            - $ref: '#/components/schemas/RoutingDefaultsModel'
            - type: 'null'
          description: Current routing defaults (null if not set)
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: >-
            "pending" when the change committed but the edge-KV sync did not
            complete immediately; the edge converges on its next read.
            Absent/null otherwise.
    CreateApiKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for the key
        key_type:
          type: string
          enum:
            - api
          description: Key type — `api` for inference
        scopes:
          type: array
          items:
            type: string
          description: Permission scopes to grant
        rate_limit_rpm:
          type: integer
          minimum: 1
          description: Per-key rate limit in requests per minute (minimum 1)
        expires_at:
          type: string
          format: date-time
          description: Expiration timestamp
        budget:
          $ref: '#/components/schemas/ApiKeyBudget'
    CreateApiKeyPublicResponse:
      type: object
      description: |
        Created API key with the full secret value.
        The `api_key` field is returned only once and cannot be retrieved again.
      required:
        - id
        - workspace_id
        - name
        - key_prefix
        - profile
        - scopes
        - is_active
        - created_at
        - api_key
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the API key
        workspace_id:
          type: string
          format: uuid
          description: Workspace this key belongs to
        name:
          type: string
          description: Human-readable name for the key
        key_prefix:
          type: string
          description: Key prefix for identification
        profile:
          type: string
          enum:
            - inference
            - management
            - mixed
          description: Key profile derived from granted scopes
        scopes:
          type: array
          items:
            type: string
          description: Granted permission scopes
        is_active:
          type: boolean
          description: Whether the key is currently active
        rate_limit_rpm:
          type:
            - integer
            - 'null'
          description: Per-key rate limit in requests per minute
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Expiration timestamp
        created_at:
          type: string
          format: date-time
          description: When the key was created
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the key was last used
        created_by_key_id:
          type:
            - string
            - 'null'
          format: uuid
          description: ID of the API key that created this key
        api_key:
          type: string
          description: |
            The full API key secret. Returned only on creation.
            Store it securely — it cannot be retrieved again.
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: Status of edge propagation. Present when KV sync is pending.
    UpdateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: Human-readable name for the key
        rate_limit_rpm:
          type: integer
          minimum: 1
          description: Per-key rate limit in requests per minute (minimum 1)
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Expiration timestamp. Send null to remove expiration.
        is_active:
          type: boolean
          description: Whether the key is active
        budget:
          $ref: '#/components/schemas/ApiKeyBudget'
    UpdateApiKeyResponse:
      type: object
      description: Updated API key metadata with optional propagation status.
      required:
        - id
        - workspace_id
        - name
        - key_prefix
        - profile
        - scopes
        - is_active
        - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the API key
        workspace_id:
          type: string
          format: uuid
          description: Workspace this key belongs to
        name:
          type: string
          description: Human-readable name for the key
        key_prefix:
          type: string
          description: Key prefix for identification
        profile:
          type: string
          enum:
            - inference
            - management
            - mixed
          description: Key profile derived from granted scopes
        scopes:
          type: array
          items:
            type: string
          description: Granted permission scopes
        is_active:
          type: boolean
          description: Whether the key is currently active
        rate_limit_rpm:
          type:
            - integer
            - 'null'
          description: Per-key rate limit in requests per minute
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Expiration timestamp
        created_at:
          type: string
          format: date-time
          description: When the key was created
        last_used_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the key was last used
        created_by_key_id:
          type:
            - string
            - 'null'
          format: uuid
          description: ID of the API key that created this key
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: Status of change propagation to edge caches
    PropagationPendingResponse:
      type: object
      description: Response when an operation is accepted but propagation is pending.
      required:
        - id
        - propagation_status
        - message
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the affected resource
        propagation_status:
          type: string
          enum:
            - pending
          description: Propagation status
        message:
          type: string
          description: Human-readable status message
    PublicWorkspaceItem:
      type: object
      description: Workspace metadata visible to API-key callers.
      required:
        - id
        - name
        - slug
        - tier
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Workspace identifier
        name:
          type: string
          description: Human-readable workspace name
        slug:
          type: string
          description: URL-safe workspace slug
        tier:
          type: string
          description: Workspace pricing tier
        created_at:
          type: string
          format: date-time
          description: When the workspace was created
        updated_at:
          type: string
          format: date-time
          description: When the workspace was last updated
    PublicWorkspaceListResponse:
      type: object
      description: Paginated list of workspaces.
      required:
        - workspaces
        - count
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/PublicWorkspaceItem'
        count:
          type: integer
          description: Total number of workspaces
    UsageAggregateItem:
      type: object
      description: Single row in aggregated usage.
      required:
        - group_key
        - request_count
        - tokens_in_total
        - tokens_out_total
        - cost_usd_total
        - error_count
        - success_rate
      properties:
        group_key:
          type: string
          description: Grouping key value (e.g. model name)
        request_count:
          type: integer
          description: Total requests in this group
        tokens_in_total:
          type: integer
          description: Total input tokens
        tokens_out_total:
          type: integer
          description: Total output tokens
        cost_usd_total:
          type: number
          description: Total cost in USD
        avg_latency_ms:
          type:
            - number
            - 'null'
          description: Average latency in milliseconds
        error_count:
          type: integer
          description: Number of failed requests
        success_rate:
          type: number
          description: Fraction of successful requests (0.0 to 1.0)
    UsageAggregateResponse:
      type: object
      description: Workspace-level usage aggregation.
      required:
        - data
        - total_requests
        - total_cost_usd
        - period_start
        - period_end
        - group_by
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UsageAggregateItem'
        total_requests:
          type: integer
          description: Total requests across all groups
        total_cost_usd:
          type: number
          description: Total cost in USD across all groups
        period_start:
          type: string
          format: date-time
          description: Start of the aggregation period
        period_end:
          type: string
          format: date-time
          description: End of the aggregation period
        group_by:
          type: string
          description: Dimension used for grouping
    RequestListItem:
      type: object
      description: Compact request metadata in list view.
      required:
        - request_id
        - timestamp
        - provider
        - success
        - http_status
      properties:
        request_id:
          type: string
          description: Unique request identifier
        timestamp:
          type: string
          format: date-time
          description: When the request was made
        provider:
          type: string
          description: Provider that handled the request
        model:
          type:
            - string
            - 'null'
          description: Requested model name
        success:
          type: boolean
          description: Whether the request succeeded
        http_status:
          type: integer
          description: HTTP status code returned
        tokens_in:
          type:
            - integer
            - 'null'
          description: Input token count
        tokens_out:
          type:
            - integer
            - 'null'
          description: Output token count
        total_latency_ms:
          type:
            - number
            - 'null'
          description: Total latency in milliseconds
        cost_usd:
          type:
            - number
            - 'null'
          description: Request cost in USD
        trace_id:
          type:
            - string
            - 'null'
          description: Trace identifier for correlation
    RequestListResponse:
      type: object
      description: Paginated list of requests.
      required:
        - requests
        - total
      properties:
        requests:
          type: array
          items:
            $ref: '#/components/schemas/RequestListItem'
        total:
          type: integer
          description: Total number of matching requests
        offset:
          type: integer
          default: 0
          description: Current offset
        limit:
          type: integer
          default: 100
          description: Items per page
    RequestDetailResponse:
      type: object
      description: Detailed metadata for a single request.
      required:
        - request_id
        - timestamp
        - provider
        - success
        - http_status
      properties:
        request_id:
          type: string
          description: Unique request identifier
        timestamp:
          type: string
          format: date-time
          description: When the request was made
        provider:
          type: string
          description: Provider that handled the request
        model:
          type:
            - string
            - 'null'
          description: Requested model name
        model_used:
          type:
            - string
            - 'null'
          description: Actual model used by the provider
        ttft_ms:
          type:
            - number
            - 'null'
          description: Time to first token in milliseconds
        total_latency_ms:
          type:
            - number
            - 'null'
          description: Total latency in milliseconds
        routing_decision_ms:
          type:
            - number
            - 'null'
          description: Routing decision time in milliseconds
        throughput_tps:
          type:
            - number
            - 'null'
          description: Throughput in tokens per second
        tokens_in:
          type:
            - integer
            - 'null'
          description: Input token count
        tokens_out:
          type:
            - integer
            - 'null'
          description: Output token count
        tokens_cached:
          type:
            - integer
            - 'null'
          description: Cached token count
        tokens_reasoning:
          type:
            - integer
            - 'null'
          description: Reasoning token count
        success:
          type: boolean
          description: Whether the request succeeded
        http_status:
          type: integer
          description: HTTP status code returned
        error_code:
          type:
            - string
            - 'null'
          description: Error code if the request failed
        streaming:
          type: boolean
          default: false
          description: Whether the request used streaming
        has_tools:
          type: boolean
          default: false
          description: Whether the request included tool definitions
        has_json_mode:
          type: boolean
          default: false
          description: Whether JSON mode was enabled
        cost_usd:
          type:
            - number
            - 'null'
          description: Request cost in USD
        attempt_index:
          type: integer
          default: 0
          description: Retry attempt index (0 = first attempt)
        is_final_attempt:
          type: boolean
          default: true
          description: Whether this was the final attempt
        trace_id:
          type:
            - string
            - 'null'
          description: Trace identifier for correlation
    BudgetListResponse:
      type: object
      description: List of budgets for a workspace.
      required:
        - budgets
        - count
      properties:
        budgets:
          type: array
          items:
            $ref: '#/components/schemas/BudgetResponse'
        count:
          type: integer
          description: Total number of budgets
    ApiKeyListResponse:
      type: object
      description: List of API keys for a workspace.
      required:
        - object
        - data
        - count
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiKeyItem'
        count:
          type: integer
          description: Total number of API keys
    KeyUsageResponse:
      type: object
      description: Usage statistics for an API key.
      required:
        - key_id
        - workspace_id
        - period
        - start_date
        - end_date
        - request_count
        - error_count
        - rate_limit_count
        - tokens_input
        - tokens_output
        - tokens_total
        - cost_usd
      properties:
        key_id:
          type: string
          description: API key identifier
        workspace_id:
          type: string
          description: Workspace identifier
        period:
          type: string
          description: Aggregation period (e.g. day, week, month)
        start_date:
          type: string
          description: Period start date
        end_date:
          type: string
          description: Period end date
        request_count:
          type: integer
          description: Total requests made with this key
        error_count:
          type: integer
          description: Number of failed requests
        rate_limit_count:
          type: integer
          description: Number of rate-limited requests
        tokens_input:
          type: integer
          description: Total input tokens
        tokens_output:
          type: integer
          description: Total output tokens
        tokens_total:
          type: integer
          description: Total tokens (input + output)
        cost_usd:
          type: number
          description: Total cost in USD
    PurchaseResponse:
      type: object
      description: Single credit purchase record.
      required:
        - id
        - amount_microdollars
        - amount_dollars
        - purchase_type
        - status
        - created_at
      properties:
        id:
          type: string
          description: Purchase identifier
        amount_microdollars:
          type: integer
          description: Amount in micro-dollars
        amount_dollars:
          type: number
          description: Amount in dollars (display convenience)
        amount_cents:
          type: integer
          description: Amount in cents (computed from micro-dollars)
        purchase_type:
          type: string
          enum:
            - manual
            - auto_reload
          description: Type of purchase
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - refunded
          description: Purchase status
        created_at:
          type: string
          format: date-time
          description: When the purchase was initiated
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the purchase completed
        failure_reason:
          type:
            - string
            - 'null'
          description: Reason for failure (if applicable)
    PurchaseHistoryResponse:
      type: object
      description: Paginated credit purchase history.
      required:
        - purchases
        - total
      properties:
        purchases:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseResponse'
        total:
          type: integer
          description: Total number of purchases
        offset:
          type: integer
          default: 0
          description: Current offset
        limit:
          type: integer
          default: 20
          description: Items per page
    UsageSummary:
      type: object
      description: Usage summary for a billing period.
      required:
        - total_requests
        - total_inference_microdollars
        - total_inference_dollars
        - total_platform_fee_microdollars
        - total_platform_fee_dollars
        - total_deducted_microdollars
        - total_deducted_dollars
        - period_start
        - period_end
      properties:
        total_requests:
          type: integer
          description: Total API requests
        total_inference_microdollars:
          type: integer
          description: Total provider costs in micro-dollars
        total_inference_dollars:
          type: number
          description: Total provider costs in dollars
        total_platform_fee_microdollars:
          type: integer
          description: Total platform fees in micro-dollars
        total_platform_fee_dollars:
          type: number
          description: Total platform fees in dollars
        total_deducted_microdollars:
          type: integer
          description: Total credits deducted in micro-dollars
        total_deducted_dollars:
          type: number
          description: Total credits deducted in dollars
        period_start:
          type: string
          format: date-time
          description: Start of the billing period
        period_end:
          type: string
          format: date-time
          description: End of the billing period
    UsageDetailItem:
      type: object
      description: Single usage entry in billing history.
      required:
        - id
        - inference_cost_microdollars
        - platform_fee_microdollars
        - total_deducted_microdollars
        - created_at
      properties:
        id:
          type: string
          description: Usage entry identifier
        request_id:
          type:
            - string
            - 'null'
          description: Associated request identifier
        model:
          type:
            - string
            - 'null'
          description: Model used
        provider:
          type:
            - string
            - 'null'
          description: Provider used
        tokens_input:
          type:
            - integer
            - 'null'
          description: Input token count
        tokens_output:
          type:
            - integer
            - 'null'
          description: Output token count
        inference_cost_microdollars:
          type: integer
          description: Provider inference cost in micro-dollars
        platform_fee_microdollars:
          type: integer
          description: Platform fee in micro-dollars
        total_deducted_microdollars:
          type: integer
          description: Total credits deducted in micro-dollars
        balance_after_microdollars:
          type:
            - integer
            - 'null'
          description: Credit balance after this entry
        api_key_source:
          type:
            - string
            - 'null'
          description: Key source (platform or byok)
        created_at:
          type: string
          format: date-time
          description: When the usage was recorded
    UsageHistoryResponse:
      type: object
      description: Paginated billing usage history with summary.
      required:
        - summary
        - usage
        - total
      properties:
        summary:
          $ref: '#/components/schemas/UsageSummary'
        usage:
          type: array
          items:
            $ref: '#/components/schemas/UsageDetailItem'
        total:
          type: integer
          description: Total number of usage entries
        offset:
          type: integer
          default: 0
          description: Current offset
        limit:
          type: integer
          default: 100
          description: Items per page
    ByokProviderItem:
      type: object
      description: A provider that accepts BYOK keys.
      required:
        - provider
        - display_name
      properties:
        provider:
          type: string
          description: Provider identifier (e.g. "openai")
        display_name:
          type: string
          description: Human-readable provider name
        default_account_tier:
          type:
            - string
            - 'null'
          description: >-
            Conservative tier used when `account_tier` is omitted and
            auto-detection is unavailable
    ByokProvidersResponse:
      type: object
      required:
        - object
        - data
        - count
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/ByokProviderItem'
        count:
          type: integer
    ByokTierItem:
      type: object
      description: An account tier option for a BYOK provider.
      required:
        - tier
        - display_name
        - data_policy
      properties:
        tier:
          type: string
          description: Tier identifier accepted as `account_tier`
        display_name:
          type: string
          description: Human-readable tier name
        data_policy:
          type: string
          enum:
            - zdr
            - no_training
            - none
          description: Data policy Auriko derives for keys on this tier
        qualification:
          type:
            - string
            - 'null'
          description: How an account qualifies for this tier
    ByokProviderTiersResponse:
      type: object
      required:
        - object
        - provider
        - data
        - count
      properties:
        object:
          type: string
          enum:
            - list
        provider:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/ByokTierItem'
        count:
          type: integer
    PublicByokKeyItem:
      type: object
      description: BYOK key metadata. Redacted — the provider secret is never returned.
      required:
        - id
        - workspace_id
        - provider
        - name
        - key_prefix
        - is_default
        - disabled
        - validation_status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the BYOK key
        workspace_id:
          type: string
          format: uuid
          description: Workspace this key belongs to
        provider:
          type: string
          description: Provider identifier
        name:
          type: string
          description: Human-readable name for the key
        key_prefix:
          type: string
          description: Masked display prefix of the submitted secret
        is_default:
          type: boolean
          description: Whether this key is the provider's default for routing
        disabled:
          type: boolean
          description: >-
            Disabled keys are excluded from routing; the secret stays encrypted
            at rest
        account_tier:
          type:
            - string
            - 'null'
          description: Provider account tier used for rate-limit and data-policy routing
        account_tier_source:
          type:
            - string
            - 'null'
          enum:
            - auto_detected
            - user_specified
            - fallback
            - null
          description: How the tier was determined
        validation_status:
          type: string
          enum:
            - valid
            - pending
            - invalid
            - error
          description: Coarse validation status (no provider diagnostics)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_validated_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the key last passed validation (null if never)
        propagation_status:
          type:
            - string
            - 'null'
          enum:
            - pending
            - null
          description: >-
            "pending" while a routing-affecting change for this key's provider
            is committed but edge propagation has not yet been applied
    ListByokKeysResponse:
      type: object
      required:
        - object
        - data
        - count
      properties:
        object:
          type: string
          enum:
            - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicByokKeyItem'
        count:
          type: integer
    CreateByokKeyRequest:
      type: object
      additionalProperties: false
      required:
        - provider
        - api_key
      properties:
        provider:
          type: string
          description: Provider identifier from `GET /v1/byok/providers`
        api_key:
          type: string
          writeOnly: true
          minLength: 10
          description: >-
            Provider secret. Accepted once at creation, encrypted at rest, and
            never returned by any endpoint.
        name:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 100
          description: Human-readable name (defaults to "<Provider> Key")
        is_default:
          type: boolean
          default: true
          description: Whether this key becomes the provider's routing default
        account_tier:
          type:
            - string
            - 'null'
          description: >-
            Provider account tier from the tiers endpoint. Omit to let Auriko
            auto-detect or use the provider's conservative default.
    UpdateByokKeyRequest:
      type: object
      additionalProperties: false
      description: >-
        At least one field is required. Provider secret fields are rejected —
        secrets are immutable.
      properties:
        name:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 100
          description: New human-readable name
        is_default:
          type:
            - boolean
            - 'null'
          description: >-
            Promote (true) or demote (false) this key as the provider's routing
            default
        account_tier:
          type:
            - string
            - 'null'
          description: Provider account tier from the tiers endpoint
        disabled:
          type:
            - boolean
            - 'null'
          description: Disable (true) to exclude the key from routing without deleting it
    ByokPropagationPendingResponse:
      type: object
      description: >-
        Response when a BYOK deletion is committed but edge propagation is
        pending.
      required:
        - id
        - propagation_status
        - message
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the affected BYOK key
        propagation_status:
          type: string
          enum:
            - pending
          description: Propagation status
        message:
          type: string
          description: Human-readable status message
    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: '#/components/schemas/ThinkingReasoningBlock'
          redacted: '#/components/schemas/RedactedReasoningBlock'
    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)
    AnthropicMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicContentBlock'
    AnthropicContentBlock:
      description: Anthropic content block. Discriminated union on `type`.
      oneOf:
        - $ref: '#/components/schemas/AnthropicTextBlock'
        - $ref: '#/components/schemas/AnthropicImageBlock'
        - $ref: '#/components/schemas/AnthropicToolUseBlock'
        - $ref: '#/components/schemas/AnthropicToolResultBlock'
        - $ref: '#/components/schemas/AnthropicThinkingBlock'
        - $ref: '#/components/schemas/AnthropicRedactedThinkingBlock'
      discriminator:
        propertyName: type
        mapping:
          text: '#/components/schemas/AnthropicTextBlock'
          image: '#/components/schemas/AnthropicImageBlock'
          tool_use: '#/components/schemas/AnthropicToolUseBlock'
          tool_result: '#/components/schemas/AnthropicToolResultBlock'
          thinking: '#/components/schemas/AnthropicThinkingBlock'
          redacted_thinking: '#/components/schemas/AnthropicRedactedThinkingBlock'
    AnthropicTextBlock:
      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
    AnthropicImageBlock:
      type: object
      required:
        - type
        - source
      properties:
        type:
          type: string
          const: image
        source:
          type: object
          required:
            - type
            - media_type
            - data
          properties:
            type:
              type: string
              const: base64
            media_type:
              type: string
              description: MIME type (e.g., image/png, image/jpeg)
            data:
              type: string
              description: Base64-encoded image data
        cache_control:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              const: ephemeral
    AnthropicToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          const: tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object
          additionalProperties: true
    AnthropicToolResultBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          const: tool_result
        tool_use_id:
          type: string
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicTextBlock'
          description: Result content (string or array of text blocks)
        is_error:
          type: boolean
    AnthropicThinkingBlock:
      type: object
      required:
        - type
        - thinking
      properties:
        type:
          type: string
          const: thinking
        thinking:
          type: string
          description: The model's thinking/reasoning content
        signature:
          type: string
          description: Cryptographic signature for multi-turn verification
    AnthropicRedactedThinkingBlock:
      type: object
      required:
        - type
        - data
      properties:
        type:
          type: string
          const: redacted_thinking
        data:
          type: string
          description: Opaque redacted thinking data
    AnthropicSystemBlock:
      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
    AnthropicThinkingConfig:
      description: Controls extended thinking behavior.
      oneOf:
        - type: object
          required:
            - type
            - budget_tokens
          properties:
            type:
              type: string
              const: enabled
            budget_tokens:
              type: integer
              minimum: 1024
              description: Maximum tokens for thinking (minimum 1024)
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: adaptive
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: disabled
    AnthropicTool:
      type: object
      required:
        - name
        - input_schema
      properties:
        name:
          type: string
          description: Tool name
        description:
          type: string
          description: Tool description
        input_schema:
          type: object
          description: JSON Schema for tool input parameters
          additionalProperties: true
    AnthropicToolChoice:
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - auto
                - any
                - none
        - type: object
          required:
            - type
            - name
          properties:
            type:
              type: string
              const: tool
            name:
              type: string
    AnthropicUsage:
      type: object
      required:
        - input_tokens
        - output_tokens
      properties:
        input_tokens:
          type: integer
          description: Input tokens that were neither read from nor written to cache
        output_tokens:
          type: integer
          description: Output tokens generated
        cache_creation_input_tokens:
          type: integer
          description: Input tokens written to cache
        cache_read_input_tokens:
          type: integer
          description: Input tokens read from cache
    AnthropicResponse:
      type: object
      required:
        - id
        - type
        - role
        - content
        - model
        - stop_reason
        - stop_sequence
        - usage
      properties:
        id:
          type: string
          description: Unique message identifier (gateway request ID)
        type:
          type: string
          const: message
        role:
          type: string
          const: assistant
        content:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicContentBlock'
          description: Content blocks (text, thinking, tool_use, etc.)
        model:
          type: string
          description: Model that generated the response (canonical model ID from request)
        stop_reason:
          type:
            - string
            - 'null'
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
            - pause_turn
            - refusal
            - null
          description: Reason generation stopped
        stop_sequence:
          type:
            - string
            - 'null'
          description: Always null (Auriko does not surface matched stop sequences)
        usage:
          $ref: '#/components/schemas/AnthropicUsage'
    AnthropicErrorResponse:
      type: object
      required:
        - type
        - error
      properties:
        type:
          type: string
          const: error
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - authentication_error
                - permission_error
                - not_found_error
                - invalid_request_error
                - request_too_large
                - rate_limit_error
                - billing_error
                - api_error
                - overloaded_error
              description: Error category
            message:
              type: string
              description: Human-readable error description
            suggestion:
              type: string
              description: >-
                Actionable fix hint for routing, capability, or model-not-found
                errors. Absent for other error types.
    CreateMessageRequest:
      type: object
      description: |
        Anthropic Messages API request body.
      required:
        - messages
        - max_tokens
      oneOf:
        - required:
            - model
        - required:
            - gateway
          properties:
            gateway:
              required:
                - models
      properties:
        model:
          type: string
          description: |
            Model ID. Mutually exclusive with `gateway.models`.
            Examples: `claude-sonnet-4-20250514`, `claude-haiku-4-5-20251001`
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicMessage'
          minItems: 1
          description: Messages in the conversation
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicSystemBlock'
          description: >-
            System prompt (string or array of text blocks with optional
            cache_control)
        max_tokens:
          type: integer
          minimum: 1
          description: Maximum output tokens to generate
        stream:
          type: boolean
          default: false
          description: Enable streaming responses (SSE)
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicTool'
          description: Tools available for the model to call
        tool_choice:
          $ref: '#/components/schemas/AnthropicToolChoice'
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: Sampling temperature
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: Nucleus sampling parameter
        top_k:
          type: integer
          minimum: 1
          description: Top-K sampling parameter
        min_p:
          type: number
          minimum: 0
          maximum: 1
          description: Min-P sampling. Forwarded to providers that support it.
        top_a:
          type: number
          minimum: 0
          maximum: 1
          description: Top-A sampling. Forwarded to providers that support it.
        repetition_penalty:
          type: number
          description: Repetition penalty. Forwarded to providers that support it.
        stop_sequences:
          type: array
          items:
            type: string
          description: Custom stop sequences
        thinking:
          $ref: '#/components/schemas/AnthropicThinkingConfig'
        metadata:
          type: object
          properties:
            user_id:
              type: string
          description: Anthropic request metadata
        gateway:
          type: object
          description: >
            Auriko gateway directives. Controls routing, metadata, and
            multi-model selection.
          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`.
          additionalProperties: false
        extensions:
          $ref: '#/components/schemas/Extensions'
        prompt_cache_key:
          type: string
          description: Prompt caching identifier
        safety_identifier:
          type: string
          description: Safety policy identifier
        verbosity:
          type: string
          description: Output verbosity control
    CountTokensRequest:
      type: object
      description: |
        Request body for /v1/messages/count_tokens.
        Token counts for non-Claude models use a reference tokenizer.
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: |
            Model to use for tokenization. For non-Claude models, a reference
            tokenizer is used (response includes X-Token-Count-Model header).
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicMessage'
          minItems: 1
          description: Messages to count tokens for
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/AnthropicSystemBlock'
          description: System prompt (counted alongside messages)
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AnthropicTool'
          description: Tools to include in token count
        tool_choice:
          $ref: '#/components/schemas/AnthropicToolChoice'
        thinking:
          $ref: '#/components/schemas/AnthropicThinkingConfig'
        gateway:
          type: object
          description: >
            Auriko gateway directives. For count_tokens, only `routing` is
            allowed.

            Other gateway keys return 400.
          properties:
            routing:
              $ref: '#/components/schemas/RoutingOptions'
          additionalProperties: false
    CountTokensResponse:
      type: object
      required:
        - input_tokens
      properties:
        input_tokens:
          type: integer
          description: Number of input tokens
    CreateResponseRequest:
      type: object
      required:
        - input
      oneOf:
        - required:
            - model
        - required:
            - gateway
          properties:
            gateway:
              required:
                - models
      description: Request body for creating a response via the Response API.
      properties:
        model:
          type: string
          description: Model ID to use (e.g., "gpt-4o", "claude-sonnet-4-20250514").
        input:
          oneOf:
            - type: string
              description: Simple text input.
            - type: array
              items:
                $ref: '#/components/schemas/ResponseInputItem'
              description: Structured input with message history and tool results.
          description: The input to generate a response for.
        instructions:
          type: string
          description: System instructions for the model.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ResponseTool'
          description: Tools available to the model.
        tool_choice:
          description: How the model should use tools.
          oneOf:
            - type: string
              enum:
                - auto
                - none
                - required
            - type: object
              properties:
                type:
                  type: string
                  const: function
                name:
                  type: string
              required:
                - type
                - name
            - type: object
              description: >-
                Non-function tool choice for hosted tools (e.g.,
                web_search_preview).
              properties:
                type:
                  type: string
                  not:
                    enum:
                      - function
              required:
                - type
              additionalProperties: true
        parallel_tool_calls:
          type: boolean
          description: Whether the model can make multiple tool calls in parallel.
        max_output_tokens:
          type: integer
          description: Maximum number of output tokens.
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Sampling temperature.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: Nucleus sampling parameter.
        top_k:
          type: integer
          description: Top-k sampling parameter.
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
          description: >-
            Number of top logprobs to return per token position. Requires
            provider logprobs support.
        stream:
          type: boolean
          description: Whether to stream the response.
        text:
          type: object
          description: Text generation configuration.
          properties:
            format:
              $ref: '#/components/schemas/ResponseTextFormat'
        reasoning:
          type: object
          description: Reasoning/thinking configuration.
          properties:
            effort:
              type: string
              enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
                - max
                - 'off'
              description: Level of reasoning effort.
            summary:
              type: string
              enum:
                - auto
                - concise
                - detailed
              description: Reasoning summary format.
            generate_summary:
              type: string
              enum:
                - auto
                - concise
                - detailed
              description: Reasoning summary format (alternative field name).
        truncation:
          type: string
          description: Truncation strategy for long inputs.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Arbitrary key-value metadata.
        include:
          type: array
          items:
            type: string
          description: Additional data to include in the response.
        user:
          type: string
          description: End-user identifier for abuse detection.
        store:
          type: boolean
          enum:
            - false
          description: Omit this field or set to false. Sending true returns 400.
        gateway:
          type: object
          description: Auriko gateway directives.
          properties:
            routing:
              $ref: '#/components/schemas/RoutingOptions'
            metadata:
              $ref: '#/components/schemas/RequestMetadata'
            models:
              type: array
              items:
                type: string
              description: Model pool for multi-model routing.
        extensions:
          $ref: '#/components/schemas/Extensions'
        prompt_cache_key:
          type: string
          description: Key for prompt caching.
        safety_identifier:
          type: string
          description: Safety policy identifier.
        frequency_penalty:
          type: number
          description: Penalizes new tokens based on their frequency in the text so far.
        presence_penalty:
          type: number
          description: >-
            Penalizes new tokens based on whether they appear in the text so
            far.
        max_tool_calls:
          type: integer
          minimum: 1
          description: >-
            Maximum number of built-in tool calls (e.g., web_search,
            code_interpreter) allowed in a response.
    ResponseObject:
      type: object
      description: A completed Response API response.
      required:
        - id
        - object
        - created_at
        - model
        - status
        - output
      properties:
        id:
          type: string
          description: Unique response identifier.
        object:
          type: string
          const: response
        created_at:
          type: integer
          description: Unix timestamp of creation.
        model:
          type: string
          description: Model used for generation.
        status:
          type: string
          enum:
            - completed
            - failed
            - incomplete
            - in_progress
          description: Response status.
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputItem'
          description: |
            Output items generated by the model. Known types include
            `message`, `function_call`, and `reasoning`. Additional types
            from the provider (e.g., `web_search_call`, `file_search_call`)
            are passed through verbatim.
        output_text:
          type: string
          description: Concatenated text output for convenience.
        parallel_tool_calls:
          type: boolean
          description: Whether parallel tool calls were enabled.
        tool_choice:
          description: Tool choice setting used.
        tools:
          type: array
          items: {}
          description: Tools that were available.
        usage:
          $ref: '#/components/schemas/ResponseUsageSchema'
        error:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
            message:
              type: string
          description: Error details if status is "failed".
        incomplete_details:
          type:
            - object
            - 'null'
          properties:
            reason:
              type: string
          description: Details if status is "incomplete".
        metadata:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
        routing_metadata:
          $ref: '#/components/schemas/RoutingMetadata'
        temperature:
          type: number
          description: Sampling temperature used.
        top_p:
          type: number
          description: Nucleus sampling parameter used.
        max_output_tokens:
          type:
            - integer
            - 'null'
          description: Maximum output tokens setting.
        frequency_penalty:
          type: number
          description: Frequency penalty setting.
        presence_penalty:
          type: number
          description: Presence penalty setting.
        top_logprobs:
          type: integer
          description: Number of top logprobs returned.
        instructions:
          type:
            - string
            - 'null'
          description: System instructions used.
        truncation:
          type: string
          description: Truncation strategy used.
        reasoning:
          type:
            - object
            - 'null'
          description: Reasoning configuration used.
        text:
          type: object
          description: Text generation configuration used.
        user:
          type:
            - string
            - 'null'
          description: End-user identifier.
        prompt_cache_key:
          type:
            - string
            - 'null'
          description: Prompt cache key used.
        safety_identifier:
          type:
            - string
            - 'null'
          description: Safety policy identifier used.
        max_tool_calls:
          type:
            - integer
            - 'null'
          description: Maximum number of built-in tool calls allowed in a response.
        store:
          type: boolean
          description: Whether the response is stored.
        previous_response_id:
          type:
            - string
            - 'null'
          description: Previous response ID for conversation continuity.
        background:
          type: boolean
          description: Whether this was a background response.
        completed_at:
          type:
            - integer
            - 'null'
          description: Unix timestamp when the response completed.
        service_tier:
          type:
            - string
            - 'null'
          description: Service tier used by the provider.
        tool_usage:
          type:
            - object
            - 'null'
          description: >-
            Built-in tool consumption metrics from the provider (e.g. image
            generation tokens, web search request counts). Present on OpenAI
            responses; absent for other providers.
    ResponseOutputItem:
      description: >
        An output item from the model. Discriminated on `type`.

        Known types: `message`, `function_call`, `reasoning`,
        `image_generation_call`.

        Unknown types from the provider are preserved verbatim.
      oneOf:
        - $ref: '#/components/schemas/ResponseMessageOutputItem'
        - $ref: '#/components/schemas/ResponseFunctionCallOutputItem'
        - $ref: '#/components/schemas/ResponseReasoningOutputItem'
        - $ref: '#/components/schemas/ResponseImageGenerationCallOutputItem'
        - type: object
          description: >
            Unknown output item type from the provider (e.g., web_search_call,
            file_search_call). Preserved verbatim.
          required:
            - type
          properties:
            type:
              type: string
              not:
                enum:
                  - message
                  - function_call
                  - reasoning
                  - image_generation_call
          additionalProperties: true
    ResponseMessageOutputItem:
      type: object
      required:
        - type
        - id
        - role
        - status
        - content
      properties:
        type:
          type: string
          const: message
        id:
          type: string
        role:
          type: string
          const: assistant
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponseOutputContentPart'
        phase:
          type: string
          description: >-
            Message phase label ("commentary" or "final_answer") emitted by
            gpt-5.4+ OpenAI models; absent otherwise — never synthesized for
            providers that did not emit it. Preserve it when resending output
            items as input.
    ResponseFunctionCallOutputItem:
      type: object
      required:
        - type
        - id
        - call_id
        - name
        - arguments
        - status
      properties:
        type:
          type: string
          const: function_call
        id:
          type: string
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
          description: JSON-encoded function arguments.
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
    ResponseReasoningOutputItem:
      type: object
      required:
        - type
        - id
        - summary
      properties:
        type:
          type: string
          const: reasoning
        id:
          type: string
        summary:
          type: array
          items:
            $ref: '#/components/schemas/ResponseReasoningSummaryBlock'
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
    ResponseImageGenerationCallOutputItem:
      type: object
      required:
        - type
        - id
        - status
        - result
      properties:
        type:
          type: string
          const: image_generation_call
        id:
          type: string
        status:
          type: string
          enum:
            - in_progress
            - completed
            - generating
            - failed
        result:
          type:
            - string
            - 'null'
          description: Base64-encoded image data, or null while in progress.
    ResponseOutputContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          const: output_text
        text:
          type: string
        annotations:
          type: array
          items: {}
        logprobs:
          type: array
          items: {}
          description: Token-level log probabilities. Present when top_logprobs is set.
    ResponseReasoningSummaryBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          const: summary_text
        text:
          type: string
    ResponseInputItem:
      description: An input item in the conversation history.
      oneOf:
        - type: object
          description: A message in the conversation.
          required:
            - role
            - content
          properties:
            type:
              type: string
              description: Optional, defaults to "message".
            role:
              type: string
              enum:
                - user
                - assistant
                - system
                - developer
            content:
              oneOf:
                - type: string
                - type: array
                  items:
                    $ref: '#/components/schemas/ResponseContentPart'
        - type: object
          description: A function call made by the model.
          required:
            - type
            - call_id
            - name
            - arguments
          properties:
            type:
              type: string
              const: function_call
            call_id:
              type: string
            name:
              type: string
            arguments:
              type: string
        - type: object
          description: Output of a function call.
          required:
            - type
            - call_id
            - output
          properties:
            type:
              type: string
              const: function_call_output
            call_id:
              type: string
            output:
              type: string
        - type: object
          description: >-
            Reasoning item from a previous response. Include in input for
            multi-turn conversations with reasoning models. Only available for
            models that support the Response API.
          required:
            - type
          properties:
            type:
              type: string
              const: reasoning
            id:
              type: string
            summary:
              type: array
              items:
                $ref: '#/components/schemas/ResponseReasoningSummaryBlock'
            encrypted_content:
              type: string
    ResponseContentPart:
      description: A content part in a message.
      oneOf:
        - type: object
          required:
            - type
            - text
          properties:
            type:
              type: string
              const: input_text
            text:
              type: string
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: input_image
            image_url:
              type: string
            detail:
              type: string
              enum:
                - auto
                - low
                - high
        - type: object
          description: >-
            Output text from a previous assistant response, used in multi-turn
            input.
          required:
            - type
            - text
          properties:
            type:
              type: string
              const: output_text
            text:
              type: string
            annotations:
              type: array
              items: {}
    ResponseTool:
      description: A tool available to the model.
      oneOf:
        - type: object
          description: A function tool.
          required:
            - type
            - name
          properties:
            type:
              type: string
              const: function
            name:
              type: string
            description:
              type: string
            parameters:
              $ref: '#/components/schemas/FunctionDefinition/properties/parameters'
            strict:
              type: boolean
        - type: object
          description: A built-in hosted tool (e.g., web_search, code_interpreter).
          required:
            - type
          properties:
            type:
              type: string
              description: Tool type identifier.
          additionalProperties: true
    ResponseTextFormat:
      description: Text output format configuration.
      oneOf:
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: text
        - type: object
          required:
            - type
          properties:
            type:
              type: string
              const: json_object
        - type: object
          required:
            - type
            - name
            - schema
          properties:
            type:
              type: string
              const: json_schema
            name:
              type: string
            schema:
              type: object
            strict:
              type: boolean
    ResponseInputTokensDetailsSchema:
      type: object
      description: Detailed breakdown of input tokens for a Response API request.
      properties:
        cached_tokens:
          type: integer
        cache_write_tokens:
          type: integer
          description: >-
            Tokens written to prompt cache. Provider-dependent: present when the
            upstream provider reports cache write details, absent otherwise.
    ResponseOutputTokensDetailsSchema:
      type: object
      description: Detailed breakdown of output tokens for a Response API request.
      properties:
        reasoning_tokens:
          type: integer
        image_tokens:
          type: integer
    ResponseUsageSchema:
      type: object
      description: Token usage for a Response API request.
      required:
        - input_tokens
        - output_tokens
        - total_tokens
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          $ref: '#/components/schemas/ResponseInputTokensDetailsSchema'
        output_tokens_details:
          $ref: '#/components/schemas/ResponseOutputTokensDetailsSchema'