OmniRoute/docs/reference/openapi.yaml

openapi: 3.1.0
info:
  title: OmniRoute API
  version: 3.8.6
  description: |
    OmniRoute is a local-first AI API proxy router. It provides an OpenAI-compatible
    endpoint that routes requests to multiple AI providers with load balancing,
    failover, and usage tracking.

    ## Base URLs
    - **Local**: `http://localhost:20128`

    ## Authentication
    All proxy endpoints require a Bearer token (API key managed via the dashboard).
    Management endpoints are protected when `requireLogin` is enabled.
  contact:
    name: OmniRoute
  license:
    name: MIT

servers:
  - url: http://localhost:20128
    description: Local development

tags:
  - name: Chat
    description: OpenAI-compatible chat completions
  - name: Messages
    description: Anthropic-compatible messages
  - name: Responses
    description: OpenAI Responses API
  - name: Embeddings
    description: Text embedding generation
  - name: Images
    description: Image generation
  - name: Audio
    description: Audio speech and transcription
  - name: Moderations
    description: Content moderation
  - name: Rerank
    description: Document reranking
  - name: Models
    description: Available model listing
  - name: Providers
    description: Provider connection management
  - name: Provider Nodes
    description: Provider node configuration
  - name: API Keys
    description: API key management
  - name: Combos
    description: Routing combo management
  - name: Settings
    description: Application settings
  - name: Compression
    description: Prompt compression, RTK filters, Caveman rules, and compression combos
  - name: Usage
    description: Usage analytics and logs
  - name: Translator
    description: Format translation debug & testing
  - name: CLI Tools
    description: CLI tool configuration management
  - name: Embedded Services
    description: >-
      Install, start, stop, and monitor locally-running embedded services (9Router, CLIProxyAPI).
      All routes are LOCAL_ONLY — accessible from loopback only (hard rule #17).
  - name: OAuth
    description: OAuth flows for provider authentication
  - name: System
    description: System management (restart, shutdown, backup)
  - name: Pricing
    description: Model pricing configuration
  - name: Cloud
    description: Cloud worker authentication and sync
  - name: Fallback
    description: Fallback chain management
  - name: Telemetry
    description: Telemetry and token health monitoring

paths:
  # ─── Proxy Endpoints ──────────────────────────────────────────

  /api/v1/chat/completions:
    post:
      tags: [Chat]
      summary: Create chat completion
      description: OpenAI-compatible chat completions endpoint. Routes to configured providers.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: Chat completion response (or SSE stream)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletionResponse"
            text/event-stream:
              schema:
                type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "502":
          description: All upstream providers failed

  /api/v1/providers/{provider}/chat/completions:
    post:
      tags: [Chat]
      summary: Create chat completion (provider-specific)
      description: Routes to a specific provider by name.
      security:
        - BearerAuth: []
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatCompletionRequest"
      responses:
        "200":
          description: Chat completion response
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/api/chat:
    post:
      tags: [Chat]
      summary: Ollama-compatible chat endpoint
      description: Provides compatibility with Ollama's /api/chat format.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Chat response (JSON or streaming)

  /api/v1/messages:
    post:
      tags: [Messages]
      summary: Create message (Anthropic-compatible)
      description: Anthropic Messages API endpoint. Routes to Claude providers.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MessagesRequest"
      responses:
        "200":
          description: Message response (or SSE stream)
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/messages/count_tokens:
    post:
      tags: [Messages]
      summary: Count tokens for a message
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Token count

  /api/v1/responses:
    post:
      tags: [Responses]
      summary: Create response (OpenAI Responses API)
      description: OpenAI Responses API endpoint.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Response object or SSE stream
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/embeddings:
    post:
      tags: [Embeddings]
      summary: Create embeddings
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input, model]
              properties:
                input:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                model:
                  type: string
      responses:
        "200":
          description: Embedding vectors

  /api/v1/providers/{provider}/embeddings:
    post:
      tags: [Embeddings]
      summary: Create embeddings (provider-specific)
      security:
        - BearerAuth: []
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Embedding vectors

  /api/v1/images/generations:
    post:
      tags: [Images]
      summary: Generate images
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [prompt]
              properties:
                prompt:
                  type: string
                model:
                  type: string
                n:
                  type: integer
                  default: 1
                size:
                  type: string
                  default: 1024x1024
      responses:
        "200":
          description: Generated images

  /api/v1/providers/{provider}/images/generations:
    post:
      tags: [Images]
      summary: Generate images (provider-specific)
      security:
        - BearerAuth: []
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Generated images

  /api/v1/audio/speech:
    post:
      tags: [Audio]
      summary: Generate speech audio
      description: Text-to-speech endpoint. Routes to configured TTS providers.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  type: string
                model:
                  type: string
                voice:
                  type: string
      responses:
        "200":
          description: Audio data

  /api/v1/audio/transcriptions:
    post:
      tags: [Audio]
      summary: Transcribe audio
      description: Audio-to-text transcription endpoint.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                model:
                  type: string
      responses:
        "200":
          description: Transcription result

  /api/v1/moderations:
    post:
      tags: [Moderations]
      summary: Create moderation
      description: Content moderation endpoint. Routes to configured moderation providers.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [input]
              properties:
                input:
                  oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
      responses:
        "200":
          description: Moderation result

  /api/v1/rerank:
    post:
      tags: [Rerank]
      summary: Rerank documents
      description: Document reranking endpoint.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [query, documents]
              properties:
                query:
                  type: string
                documents:
                  type: array
                  items:
                    type: string
                model:
                  type: string
      responses:
        "200":
          description: Reranked documents

  /api/v1:
    get:
      tags: [System]
      summary: API v1 root endpoint
      description: Returns basic API info and status.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: API info

  /api/v1/models:
    get:
      tags: [Models]
      summary: List available models
      description: Returns all models available across configured providers.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: list
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Model"

  /api/v1/providers/{provider}/models:
    get:
      tags: [Models]
      summary: List models for a specific provider
      description: Returns only models for the selected provider with provider prefix removed from each model id.
      security:
        - BearerAuth: []
      parameters:
        - in: path
          name: provider
          required: true
          schema:
            type: string
          description: Provider id or alias (for example `openai`, `claude`, `cc`).
      responses:
        "200":
          description: Provider-scoped model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: list
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Model"
        "400":
          description: Unknown provider

  /api/models:
    get:
      tags: [Models]
      summary: List models (management)
      responses:
        "200":
          description: Internal model list with aliases

  /api/models/alias:
    post:
      tags: [Models]
      summary: Create or update a model alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Alias created/updated

  /api/models/catalog:
    get:
      tags: [Models]
      summary: Get full model catalog
      responses:
        "200":
          description: Complete catalog with all providers

  # ─── Management Endpoints ──────────────────────────────────────

  /api/providers:
    get:
      tags: [Providers]
      summary: List provider connections
      responses:
        "200":
          description: Provider connection list
          content:
            application/json:
              schema:
                type: object
                properties:
                  connections:
                    type: array
                    items:
                      $ref: "#/components/schemas/ProviderConnection"
    post:
      tags: [Providers]
      summary: Create provider connection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProviderConnectionCreate"
      responses:
        "201":
          description: Created provider connection

  /api/providers/{id}:
    get:
      tags: [Providers]
      summary: Get provider connection
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Provider connection details
        "404":
          description: Provider not found
    patch:
      tags: [Providers]
      summary: Update provider connection
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ProviderConnectionCreate"
      responses:
        "200":
          description: Updated provider
    delete:
      tags: [Providers]
      summary: Delete provider connection
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Provider deleted

  /api/providers/{id}/test:
    post:
      tags: [Providers]
      summary: Test provider connection
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Test result

  /api/providers/{id}/models:
    get:
      tags: [Providers]
      summary: List models for a provider
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Provider model list

  /api/providers/test-batch:
    post:
      tags: [Providers]
      summary: Test multiple providers at once
      responses:
        "200":
          description: Batch test results

  /api/providers/validate:
    post:
      tags: [Providers]
      summary: Validate provider credentials
      responses:
        "200":
          description: Validation result

  /api/providers/client:
    get:
      tags: [Providers]
      summary: Get client-side provider info
      responses:
        "200":
          description: Provider info for frontend

  /api/provider-nodes:
    get:
      tags: [Provider Nodes]
      summary: List provider nodes
      responses:
        "200":
          description: Provider node list
    post:
      tags: [Provider Nodes]
      summary: Create provider node
      responses:
        "201":
          description: Created node

  /api/provider-nodes/{id}:
    patch:
      tags: [Provider Nodes]
      summary: Update provider node
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Updated node
    delete:
      tags: [Provider Nodes]
      summary: Delete provider node
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Node deleted

  /api/provider-nodes/validate:
    post:
      tags: [Provider Nodes]
      summary: Validate a provider node
      responses:
        "200":
          description: Validation result

  /api/provider-models:
    get:
      tags: [Provider Nodes]
      summary: List provider models
      responses:
        "200":
          description: Provider model list

  /api/keys:
    get:
      tags: [API Keys]
      summary: List API keys
      responses:
        "200":
          description: API key list
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      $ref: "#/components/schemas/ApiKey"
    post:
      tags: [API Keys]
      summary: Create API key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [label]
              properties:
                label:
                  type: string
      responses:
        "201":
          description: Created API key (includes full key value)

  /api/keys/{id}:
    delete:
      tags: [API Keys]
      summary: Delete API key
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Key deleted

  /api/combos:
    get:
      tags: [Combos]
      summary: List routing combos
      responses:
        "200":
          description: Combo list
    post:
      tags: [Combos]
      summary: Create routing combo
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ComboCreate"
      responses:
        "201":
          description: Created combo

  /api/combos/{id}:
    patch:
      tags: [Combos]
      summary: Update combo
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Updated combo
    delete:
      tags: [Combos]
      summary: Delete combo
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Combo deleted

  /api/combos/metrics:
    get:
      tags: [Combos]
      summary: Get combo metrics
      responses:
        "200":
          description: Metrics for combos

  /api/combos/test:
    post:
      tags: [Combos]
      summary: Test a combo configuration
      responses:
        "200":
          description: Test result

  /api/settings:
    get:
      tags: [Settings]
      summary: Get application settings
      responses:
        "200":
          description: Current settings
    patch:
      tags: [Settings]
      summary: Update settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated settings

  /api/settings/compression:
    get:
      tags: [Compression]
      summary: Get global compression settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Current compression settings
    put:
      tags: [Compression]
      summary: Update global compression settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                defaultMode:
                  type: string
                  enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
                autoTriggerMode:
                  type: string
                  enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
                autoTriggerTokens:
                  type: integer
                  minimum: 0
                rtkConfig:
                  type: object
                  additionalProperties: true
                stackedPipeline:
                  type: array
                  items:
                    type: object
      responses:
        "200":
          description: Updated compression settings

  /api/compression/preview:
    post:
      tags: [Compression]
      summary: Preview compression for a message payload
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [messages, mode]
              properties:
                mode:
                  type: string
                  enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
                messages:
                  type: array
                  items:
                    type: object
                    required: [role, content]
                    properties:
                      role:
                        type: string
                      content:
                        oneOf:
                          - type: string
                          - type: array
                            items: {}
                config:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Compression preview with diff, validation, and stats

  /api/compression/language-packs:
    get:
      tags: [Compression]
      summary: List Caveman compression language packs
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Available languages and rule-pack metadata

  /api/compression/rules:
    get:
      tags: [Compression]
      summary: List Caveman compression rule metadata
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Caveman rule metadata

  /api/context/rtk/config:
    get:
      tags: [Compression]
      summary: Get RTK compression settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Current RTK config
    put:
      tags: [Compression]
      summary: Update RTK compression settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                intensity:
                  type: string
                  enum: [minimal, standard, aggressive]
                customFiltersEnabled:
                  type: boolean
                trustProjectFilters:
                  type: boolean
                rawOutputRetention:
                  type: string
                  enum: [never, failures, always]
                rawOutputMaxBytes:
                  type: integer
      responses:
        "200":
          description: Updated RTK config

  /api/context/rtk/filters:
    get:
      tags: [Compression]
      summary: List RTK filters and load diagnostics
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: RTK filter catalog and diagnostics

  /api/context/rtk/test:
    post:
      tags: [Compression]
      summary: Run RTK compression preview for text
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                command:
                  type: string
                config:
                  type: object
                  additionalProperties: true
      responses:
        "200":
          description: Detection and RTK compression result

  /api/context/rtk/raw-output/{id}:
    get:
      tags: [Compression]
      summary: Read retained redacted RTK raw output
      security:
        - ManagementSessionAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            pattern: "^[a-f0-9]{24}$"
      responses:
        "200":
          description: Raw output text
        "404":
          description: Raw output not found

  /api/settings/payload-rules:
    get:
      tags: [Settings]
      summary: Get payload rules configuration
      description: |
        Returns the current payload rules used to mutate outgoing request payloads before they
        are sent upstream.

        Requires a dashboard management session cookie when management auth is enabled.
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Current payload rules configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadRulesConfig"
        "401":
          $ref: "#/components/responses/ManagementAuthenticationRequired"
        "403":
          $ref: "#/components/responses/ManagementInvalidToken"
        "500":
          description: Failed to read payload rules configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"
    put:
      tags: [Settings]
      summary: Update payload rules configuration
      description: |
        Persists and hot reloads payload rules. The legacy input field `default-raw` is accepted
        on writes and normalized to `defaultRaw` in responses/runtime state.

        Requires a dashboard management session cookie when management auth is enabled.
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePayloadRulesRequest"
      responses:
        "200":
          description: Updated payload rules configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PayloadRulesConfig"
        "400":
          $ref: "#/components/responses/ValidationError"
        "401":
          $ref: "#/components/responses/ManagementAuthenticationRequired"
        "403":
          $ref: "#/components/responses/ManagementInvalidToken"
        "500":
          description: Failed to update payload rules configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiErrorResponse"

  /api/settings/combo-defaults:
    get:
      tags: [Settings]
      summary: Get combo default settings
      responses:
        "200":
          description: Default combo settings

  /api/settings/proxy:
    get:
      tags: [Settings]
      summary: Get proxy settings
      responses:
        "200":
          description: Current proxy settings
    patch:
      tags: [Settings]
      summary: Update proxy settings
      responses:
        "200":
          description: Updated proxy settings

  /api/settings/proxy/test:
    post:
      tags: [Settings]
      summary: Test proxy connection
      responses:
        "200":
          description: Test result

  /api/settings/require-login:
    post:
      tags: [Settings]
      summary: Toggle login requirement
      responses:
        "200":
          description: Updated

  /api/settings/ip-filter:
    get:
      tags: [Settings]
      summary: Get IP filter configuration
      description: Returns the current IP filter settings including blacklist, whitelist, and temp bans.
      responses:
        "200":
          description: IP filter configuration
    put:
      tags: [Settings]
      summary: Update IP filter configuration
      description: |
        Configure IP filtering with blacklist/whitelist modes, add/remove individual IPs, and manage temp bans.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                mode:
                  type: string
                  enum: [blacklist, whitelist]
                blacklist:
                  type: array
                  items:
                    type: string
                whitelist:
                  type: array
                  items:
                    type: string
                addBlacklist:
                  type: string
                removeBlacklist:
                  type: string
                addWhitelist:
                  type: string
                removeWhitelist:
                  type: string
                tempBan:
                  type: object
                  properties:
                    ip:
                      type: string
                    durationMs:
                      type: integer
                    reason:
                      type: string
                removeBan:
                  type: string
      responses:
        "200":
          description: Updated IP filter configuration

  /api/settings/system-prompt:
    get:
      tags: [Settings]
      summary: Get system prompt configuration
      description: Returns the current system prompt injection settings.
      responses:
        "200":
          description: System prompt configuration
    put:
      tags: [Settings]
      summary: Update system prompt configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                enabled:
                  type: boolean
      responses:
        "200":
          description: Updated system prompt configuration

  /api/settings/thinking-budget:
    get:
      tags: [Settings]
      summary: Get thinking budget configuration
      description: Returns the current thinking/reasoning budget settings for AI models.
      responses:
        "200":
          description: Thinking budget configuration
    put:
      tags: [Settings]
      summary: Update thinking budget configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  description: Thinking mode (e.g., auto, manual, disabled)
                customBudget:
                  type: integer
                  minimum: 0
                  maximum: 131072
                effortLevel:
                  type: string
                  enum: [none, low, medium, high]
      responses:
        "200":
          description: Updated thinking budget configuration

  /api/rate-limit:
    get:
      tags: [Settings]
      summary: Get rate limit configuration
      responses:
        "200":
          description: Rate limit settings
    post:
      tags: [Settings]
      summary: Update rate limit configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated rate limit settings

  /api/tags:
    get:
      tags: [System]
      summary: List Ollama-compatible model tags
      description: Returns models in Ollama /api/tags format for Ollama client compatibility
      responses:
        "200":
          description: Ollama model tags

  # ─── Usage & Analytics ─────────────────────────────────────────

  /api/usage/analytics:
    get:
      tags: [Usage]
      summary: Get usage analytics
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [day, week, month]
            default: day
      responses:
        "200":
          description: Usage analytics data

  /api/usage/call-logs:
    get:
      tags: [Usage]
      summary: Get call logs
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Paginated call logs

  /api/usage/call-logs/{id}:
    get:
      tags: [Usage]
      summary: Get a specific call log
      parameters:
        - $ref: "#/components/parameters/ResourceId"
      responses:
        "200":
          description: Call log detail

  /api/usage/{connectionId}:
    get:
      tags: [Usage]
      summary: Get usage for a specific connection
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Connection usage data

  /api/usage/history:
    get:
      tags: [Usage]
      summary: Get usage history
      responses:
        "200":
          description: Historical usage data

  /api/usage/logs:
    get:
      tags: [Usage]
      summary: Get usage logs
      responses:
        "200":
          description: Usage log entries

  /api/usage/proxy-logs:
    get:
      tags: [Usage]
      summary: Get proxy logs
      responses:
        "200":
          description: Proxy log entries

  /api/usage/request-logs:
    get:
      tags: [Usage]
      summary: Get request logs
      responses:
        "200":
          description: Request log entries

  /api/usage/budget:
    get:
      tags: [Usage]
      summary: Get usage budget status
      description: Returns current budget limits and consumption.
      responses:
        "200":
          description: Budget status
    post:
      tags: [Usage]
      summary: Configure usage budget
      description: Set or update budget limits for usage tracking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated budget configuration

  # ─── Pricing ───────────────────────────────────────────────────

  /api/pricing:
    get:
      tags: [Pricing]
      summary: Get model pricing
      responses:
        "200":
          description: Current pricing configuration
    post:
      tags: [Pricing]
      summary: Set model pricing
      responses:
        "200":
          description: Updated pricing

  /api/pricing/defaults:
    get:
      tags: [Pricing]
      summary: Get default pricing
      responses:
        "200":
          description: Default pricing data

  /api/pricing/models:
    get:
      tags: [Pricing]
      summary: Get pricing per model
      description: Returns pricing information organized by model.
      responses:
        "200":
          description: Per-model pricing data

  # ─── Translator ────────────────────────────────────────────────

  /api/translator/detect:
    post:
      tags: [Translator]
      summary: Detect request format
      description: Detects the API format of a request body (OpenAI, Claude, Gemini, etc.)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [body]
              properties:
                body:
                  type: object
      responses:
        "200":
          description: Detected format

  /api/translator/translate:
    post:
      tags: [Translator]
      summary: Translate between formats
      description: Converts a request between API formats (e.g. Claude → OpenAI)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sourceFormat, targetFormat, body]
              properties:
                step:
                  type: string
                sourceFormat:
                  type: string
                targetFormat:
                  type: string
                provider:
                  type: string
                body:
                  type: object
      responses:
        "200":
          description: Translated request

  /api/translator/send:
    post:
      tags: [Translator]
      summary: Send translated request to provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [provider, body]
              properties:
                provider:
                  type: string
                body:
                  type: object
      responses:
        "200":
          description: Provider response (may be SSE stream)

  /api/translator/history:
    get:
      tags: [Translator]
      summary: Get translation history
      description: Returns recent translation events for the Live Monitor
      responses:
        "200":
          description: Translation history entries

  # ─── CLI Tools ─────────────────────────────────────────────────

  /api/cli-tools/backups:
    get:
      tags: [CLI Tools]
      summary: List CLI tool backups
      responses:
        "200":
          description: Backup list
    post:
      tags: [CLI Tools]
      summary: Create CLI tool backup
      responses:
        "200":
          description: Backup created

  /api/cli-tools/runtime/{toolId}:
    get:
      tags: [CLI Tools]
      summary: Get runtime status for a CLI tool
      parameters:
        - name: toolId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Runtime status

  /api/cli-tools/guide-settings/{toolId}:
    get:
      tags: [CLI Tools]
      summary: Get guide settings for a tool
      parameters:
        - name: toolId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Guide settings

  /api/cli-tools/antigravity-mitm:
    get:
      tags: [CLI Tools]
      summary: Get Antigravity MITM proxy settings
      responses:
        "200":
          description: MITM proxy configuration
    post:
      tags: [CLI Tools]
      summary: Update Antigravity MITM proxy settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated MITM proxy configuration
    delete:
      tags: [CLI Tools]
      summary: Reset Antigravity MITM proxy settings
      responses:
        "200":
          description: MITM proxy settings reset

  /api/cli-tools/antigravity-mitm/alias:
    get:
      tags: [CLI Tools]
      summary: Get Antigravity MITM alias configuration
      responses:
        "200":
          description: Alias configuration
    put:
      tags: [CLI Tools]
      summary: Update Antigravity MITM alias configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated alias configuration

  /api/cli-tools/claude-settings:
    get:
      tags: [CLI Tools]
      summary: Get Claude CLI settings
      responses:
        "200":
          description: Claude CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply Claude CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Claude CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset Claude CLI settings
      responses:
        "200":
          description: Claude CLI settings reset

  /api/cli-tools/cline-settings:
    get:
      tags: [CLI Tools]
      summary: Get Cline CLI settings
      responses:
        "200":
          description: Cline CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply Cline CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Cline CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset Cline CLI settings
      responses:
        "200":
          description: Cline CLI settings reset

  /api/cli-tools/codex-profiles:
    get:
      tags: [CLI Tools]
      summary: Get Codex profiles
      responses:
        "200":
          description: Codex profile list
    post:
      tags: [CLI Tools]
      summary: Create Codex profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Profile created
    put:
      tags: [CLI Tools]
      summary: Update Codex profile
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Profile updated
    delete:
      tags: [CLI Tools]
      summary: Delete Codex profile
      responses:
        "200":
          description: Profile deleted

  /api/cli-tools/codex-settings:
    get:
      tags: [CLI Tools]
      summary: Get Codex CLI settings
      responses:
        "200":
          description: Codex CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply Codex CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Codex CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset Codex CLI settings
      responses:
        "200":
          description: Codex CLI settings reset

  /api/cli-tools/droid-settings:
    get:
      tags: [CLI Tools]
      summary: Get Droid CLI settings
      responses:
        "200":
          description: Droid CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply Droid CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Droid CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset Droid CLI settings
      responses:
        "200":
          description: Droid CLI settings reset

  /api/cli-tools/kilo-settings:
    get:
      tags: [CLI Tools]
      summary: Get Kilo CLI settings
      responses:
        "200":
          description: Kilo CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply Kilo CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Kilo CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset Kilo CLI settings
      responses:
        "200":
          description: Kilo CLI settings reset

  /api/cli-tools/openclaw-settings:
    get:
      tags: [CLI Tools]
      summary: Get OpenClaw CLI settings
      responses:
        "200":
          description: OpenClaw CLI configuration
    post:
      tags: [CLI Tools]
      summary: Apply OpenClaw CLI settings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: OpenClaw CLI settings applied
    delete:
      tags: [CLI Tools]
      summary: Reset OpenClaw CLI settings
      responses:
        "200":
          description: OpenClaw CLI settings reset

  # ─── Embedded Services ─────────────────────────────────────────
  # All routes LOCAL_ONLY (loopback only) — hard rule #17.
  # See docs/frameworks/EMBEDDED-SERVICES.md for full reference.

  /api/services/9router/install:
    post:
      tags: [Embedded Services]
      summary: Install 9Router from npm
      description: >-
        Installs the `9router` npm package under DATA_DIR/services/9router/.
        Uses execFile (no shell interpolation — hard rule #13).
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  default: latest
                  description: npm version tag or semver to install
      responses:
        "200":
          description: Install succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  installedVersion:
                    type: string
                  path:
                    type: string
        "400":
          description: Invalid request body
        "500":
          description: npm install failed

  /api/services/9router/start:
    post:
      tags: [Embedded Services]
      summary: Start 9Router
      description: >-
        Spawns the 9Router process. Idempotent if already running.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service started (or already running)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"
        "409":
          description: 9Router is not installed
        "503":
          description: Start failed

  /api/services/9router/stop:
    post:
      tags: [Embedded Services]
      summary: Stop 9Router
      description: >-
        Gracefully stops 9Router (SIGTERM → 15 s → SIGKILL). Idempotent.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"
        "503":
          description: Stop failed

  /api/services/9router/restart:
    post:
      tags: [Embedded Services]
      summary: Restart 9Router
      description: >-
        Equivalent to stop() then start() under the operation lock.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service restarted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"

  /api/services/9router/update:
    post:
      tags: [Embedded Services]
      summary: Update 9Router to a newer npm version
      description: >-
        Stops the service (if running), installs the newer npm version, then restarts.
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  default: latest
      responses:
        "200":
          description: Update succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  previousVersion:
                    type: string
                  installedVersion:
                    type: string
        "400":
          description: Invalid request body
        "500":
          description: Update failed

  /api/services/9router/rotate-key:
    post:
      tags: [Embedded Services]
      summary: Rotate the 9Router API key
      description: >-
        Generates a new API key, encrypts it at-rest, and restarts the service to
        apply it. The plaintext key is never returned.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Key rotated
          content:
            application/json:
              schema:
                type: object
                properties:
                  keyRotated:
                    type: boolean
                  restarted:
                    type: boolean
        "500":
          description: Rotation failed

  /api/services/9router/status:
    get:
      tags: [Embedded Services]
      summary: Get 9Router status
      description: >-
        Returns combined live supervisor state and DB metadata.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Status response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatusExtended"
        "500":
          description: Status read failed

  /api/services/9router/auto-start:
    post:
      tags: [Embedded Services]
      summary: Toggle 9Router auto-start
      description: >-
        When enabled, 9Router starts automatically on the next OmniRoute boot.
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled:
                  type: boolean
      responses:
        "200":
          description: Auto-start flag updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  autoStart:
                    type: boolean
        "400":
          description: Invalid request body

  /api/services/cliproxy/install:
    post:
      tags: [Embedded Services]
      summary: Install CLIProxyAPI from npm
      description: >-
        Installs the CLIProxyAPI package under DATA_DIR/services/cliproxy/.
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  default: latest
      responses:
        "200":
          description: Install succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  installedVersion:
                    type: string
        "400":
          description: Invalid request body
        "500":
          description: npm install failed

  /api/services/cliproxy/start:
    post:
      tags: [Embedded Services]
      summary: Start CLIProxyAPI
      description: >-
        Spawns the CLIProxyAPI process. Idempotent if already running.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"
        "409":
          description: CLIProxyAPI is not installed
        "503":
          description: Start failed

  /api/services/cliproxy/stop:
    post:
      tags: [Embedded Services]
      summary: Stop CLIProxyAPI
      description: >-
        Gracefully stops CLIProxyAPI. Idempotent.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"

  /api/services/cliproxy/restart:
    post:
      tags: [Embedded Services]
      summary: Restart CLIProxyAPI
      description: >-
        stop() then start() under the operation lock.
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Service restarted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"

  /api/services/cliproxy/update:
    post:
      tags: [Embedded Services]
      summary: Update CLIProxyAPI to a newer npm version
      description: >-
        Stops, installs newer version, restarts.
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  type: string
                  default: latest
      responses:
        "200":
          description: Update succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  installedVersion:
                    type: string
        "500":
          description: Update failed

  /api/services/cliproxy/status:
    get:
      tags: [Embedded Services]
      summary: Get CLIProxyAPI status
      description: >-
        Returns live supervisor state and DB metadata (no apiKeyMasked — CLIProxyAPI
        does not use an injected API key).
        **LOCAL_ONLY** — loopback only.
      responses:
        "200":
          description: Status response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceStatus"

  /api/services/cliproxy/auto-start:
    post:
      tags: [Embedded Services]
      summary: Toggle CLIProxyAPI auto-start
      description: >-
        When enabled, CLIProxyAPI starts automatically on the next OmniRoute boot.
        **LOCAL_ONLY** — loopback only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [enabled]
              properties:
                enabled:
                  type: boolean
      responses:
        "200":
          description: Auto-start flag updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  autoStart:
                    type: boolean
        "400":
          description: Invalid request body

  /api/services/{name}/logs:
    get:
      tags: [Embedded Services]
      summary: Stream service logs via SSE
      description: >-
        Returns a Server-Sent Events stream from the service's in-memory ring buffer
        (5 MB, circular). Sends a `snapshot` event with historical lines first, then
        live `log` events, plus a `heartbeat` every 15 s.
        **LOCAL_ONLY** — loopback only.
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
            enum: [9router, cliproxy]
        - name: tail
          in: query
          schema:
            type: integer
            default: 200
            maximum: 1000
          description: Number of historical lines to include in the initial snapshot
        - name: filter
          in: query
          schema:
            type: string
            maxLength: 200
          description: >-
            Case-insensitive substring filter applied to log lines.
            No regex — ReDoS-safe by design.
      responses:
        "200":
          description: SSE log stream
          content:
            text/event-stream:
              schema:
                type: string
                description: >-
                  Events: `snapshot` (LogLine[]), `log` (LogLine), `heartbeat` ({})
        "400":
          description: filter parameter exceeds maximum length
        "404":
          description: Service not found

  # ─── OAuth ─────────────────────────────────────────────────────

  /api/oauth/{provider}/{action}:
    get:
      tags: [OAuth]
      summary: OAuth flow handler
      description: Handles OAuth authorization and callback for providers
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
        - name: action
          in: path
          required: true
          schema:
            type: string
            enum: [authorize, callback, refresh, status]
      responses:
        "200":
          description: OAuth flow response
        "302":
          description: Redirect to provider auth page

  /api/oauth/cursor/auto-import:
    get:
      tags: [OAuth]
      summary: Auto-import Cursor OAuth credentials
      description: Automatically detects and imports Cursor credentials from local config.
      responses:
        "200":
          description: Import result

  /api/oauth/cursor/import:
    get:
      tags: [OAuth]
      summary: Get Cursor import status
      responses:
        "200":
          description: Current import status
    post:
      tags: [OAuth]
      summary: Import Cursor OAuth credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Credentials imported

  /api/oauth/kiro/auto-import:
    get:
      tags: [OAuth]
      summary: Auto-import Kiro OAuth credentials
      description: Automatically detects and imports Kiro credentials from local config.
      responses:
        "200":
          description: Import result

  /api/oauth/kiro/import:
    get:
      tags: [OAuth]
      summary: Get Kiro import status
      responses:
        "200":
          description: Current import status
    post:
      tags: [OAuth]
      summary: Import Kiro OAuth credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Credentials imported

  /api/oauth/kiro/social-authorize:
    get:
      tags: [OAuth]
      summary: Initiate Kiro social OAuth authorization
      description: Starts the social OAuth flow for Kiro.
      responses:
        "302":
          description: Redirect to OAuth provider

  /api/oauth/kiro/social-exchange:
    post:
      tags: [OAuth]
      summary: Exchange Kiro social OAuth token
      description: Exchanges the authorization code for access tokens.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Token exchange result

  # ─── Cloud ─────────────────────────────────────────────────────

  /api/cloud/auth:
    post:
      tags: [Cloud]
      summary: Authenticate with cloud worker
      description: Authenticates with the OmniRoute cloud worker for remote access.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Authentication result

  /api/cloud/credentials/update:
    put:
      tags: [Cloud]
      summary: Update cloud worker credentials
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Credentials updated

  /api/cloud/model/resolve:
    post:
      tags: [Cloud]
      summary: Resolve model via cloud
      description: Resolves a model request through the cloud worker.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Resolved model info

  /api/cloud/models/alias:
    get:
      tags: [Cloud]
      summary: Get cloud model aliases
      responses:
        "200":
          description: Cloud model alias list
    put:
      tags: [Cloud]
      summary: Update cloud model alias
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Alias updated

  # ─── Fallback ──────────────────────────────────────────────────

  /api/fallback/chains:
    get:
      tags: [Fallback]
      summary: List fallback chains
      description: Returns all registered fallback chains for model routing.
      responses:
        "200":
          description: Fallback chain list
    post:
      tags: [Fallback]
      summary: Create fallback chain
      description: Registers a fallback routing chain for a model.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model, chain]
              properties:
                model:
                  type: string
                chain:
                  type: array
                  items:
                    type: object
                    properties:
                      provider:
                        type: string
                      priority:
                        type: integer
                      enabled:
                        type: boolean
      responses:
        "200":
          description: Fallback chain created
    delete:
      tags: [Fallback]
      summary: Delete fallback chain
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [model]
              properties:
                model:
                  type: string
      responses:
        "200":
          description: Fallback chain deleted

  # ─── System ────────────────────────────────────────────────────

  /api/auth/login:
    post:
      tags: [System]
      summary: Authenticate user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [password]
              properties:
                password:
                  type: string
      responses:
        "200":
          description: JWT token returned
        "401":
          description: Invalid password

  /api/auth/logout:
    post:
      tags: [System]
      summary: Log out
      responses:
        "200":
          description: Session cleared

  /api/init:
    get:
      tags: [System]
      summary: Initialize application
      responses:
        "200":
          description: Init status

  /api/restart:
    post:
      tags: [System]
      summary: Restart the application
      responses:
        "200":
          description: Restart initiated

  /api/shutdown:
    post:
      tags: [System]
      summary: Shutdown the application
      x-always-protected: true
      responses:
        "200":
          description: Shutdown initiated

  /api/db-backups:
    get:
      tags: [System]
      summary: List database backups
      responses:
        "200":
          description: Backup list
    post:
      tags: [System]
      summary: Create database backup
      responses:
        "200":
          description: Backup created

  /api/storage/health:
    get:
      tags: [System]
      summary: Check storage health
      responses:
        "200":
          description: Storage health status

  /api/sync/cloud:
    post:
      tags: [System]
      summary: Sync with cloud
      responses:
        "200":
          description: Sync result

  /api/sync/initialize:
    post:
      tags: [System]
      summary: Initialize cloud sync
      responses:
        "200":
          description: Sync initialized

  # ─── Resilience & Monitoring ────────────────────────────────────

  /api/resilience:
    get:
      tags: [System]
      summary: Get resilience configuration
      responses:
        "200":
          description: Request queue, connection cooldown, provider breaker, and wait settings
    patch:
      tags: [System]
      summary: Update resilience configuration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Updated resilience configuration

  /api/resilience/reset:
    post:
      tags: [System]
      summary: Reset circuit breakers
      responses:
        "200":
          description: Circuit breakers reset

  /api/monitoring/health:
    get:
      tags: [System]
      summary: System health check
      description: Returns system health including uptime, memory, circuit breakers, rate limits
      responses:
        "200":
          description: Health status

  /api/rate-limits:
    get:
      tags: [System]
      summary: Get per-account rate limit status
      responses:
        "200":
          description: Rate limit status by account

  /api/sessions:
    get:
      tags: [System]
      summary: Get active sessions
      responses:
        "200":
          description: Active session list

  /api/cache:
    get:
      tags: [System]
      summary: Get cache statistics
      responses:
        "200":
          description: Semantic cache and idempotency stats
    delete:
      tags: [System]
      summary: Clear all caches
      responses:
        "200":
          description: Caches cleared

  /api/cache/stats:
    get:
      tags: [System]
      summary: Get detailed cache statistics
      description: Returns detailed statistics for all cache layers.
      responses:
        "200":
          description: Detailed cache stats
    delete:
      tags: [System]
      summary: Clear cache statistics
      responses:
        "200":
          description: Cache stats cleared

  # ─── Telemetry & Token Health ───────────────────────────────────

  /api/telemetry/summary:
    get:
      tags: [Telemetry]
      summary: Get telemetry summary
      description: Returns aggregated telemetry data including request metrics and performance stats.
      responses:
        "200":
          description: Telemetry summary data

  /api/token-health:
    get:
      tags: [Telemetry]
      summary: Get token health status
      description: Returns health status of OAuth tokens across all providers.
      responses:
        "200":
          description: Token health status

  # ─── Evals & Policies ──────────────────────────────────────────

  /api/evals:
    get:
      tags: [System]
      summary: List eval suites
      responses:
        "200":
          description: Eval suite list
    post:
      tags: [System]
      summary: Run evaluation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Eval results

  /api/evals/{suiteId}:
    get:
      tags: [System]
      summary: Get eval suite details
      parameters:
        - name: suiteId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Eval suite details

  /api/policies:
    get:
      tags: [System]
      summary: List routing policies
      responses:
        "200":
          description: Policy list
    post:
      tags: [System]
      summary: Create routing policy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Created policy
    delete:
      tags: [System]
      summary: Delete routing policy
      responses:
        "200":
          description: Policy deleted

  /api/compliance/audit-log:
    get:
      tags: [System]
      summary: Get compliance audit log
      description: >
        Returns paginated audit log entries. Use `level=high` to filter to
        high-level actions only (powers the Activity feed). Use `level=all`
        (default) for full compliance table.
      security:
        - bearerAuth: []
      parameters:
        - name: level
          in: query
          schema:
            type: string
            enum: [high, all]
            default: all
          description: "high = Activity feed events only; all = all audit events"
        - name: action
          in: query
          schema:
            type: string
          description: Filter by exact action string (e.g. "provider.added")
        - name: actor
          in: query
          schema:
            type: string
          description: Filter by actor identifier
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 500
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Audit log entries
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  # ─── Quota Sharing (Group B, plan 22) ────────────────────────────

  /api/quota/pools:
    get:
      tags: [Quota]
      summary: List quota pools
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Array of QuotaPool objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/QuotaPool"
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    post:
      tags: [Quota]
      summary: Create quota pool
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PoolCreate"
      responses:
        "201":
          description: Pool created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuotaPool"
        "400":
          description: Validation error (Zod)
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  /api/quota/pools/{id}:
    get:
      tags: [Quota]
      summary: Get quota pool by ID
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: QuotaPool object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuotaPool"
        "401":
          description: Unauthorized
        "404":
          description: Pool not found
        "500":
          description: Internal server error
    patch:
      tags: [Quota]
      summary: Update quota pool (name or allocations)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PoolUpdate"
      responses:
        "200":
          description: Updated pool
        "400":
          description: Validation error
        "401":
          description: Unauthorized
        "404":
          description: Pool not found
        "500":
          description: Internal server error
    delete:
      tags: [Quota]
      summary: Delete quota pool
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deleted
        "401":
          description: Unauthorized
        "404":
          description: Pool not found
        "500":
          description: Internal server error

  /api/quota/pools/{id}/usage:
    get:
      tags: [Quota]
      summary: Get pool usage snapshot (per-key consumption + burn rate)
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: PoolUsageSnapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PoolUsageSnapshot"
        "401":
          description: Unauthorized
        "404":
          description: Pool not found
        "500":
          description: Internal server error

  /api/quota/plans:
    get:
      tags: [Quota]
      summary: List resolved provider plans (catalog + manual overrides)
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Array of ProviderPlan
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  /api/quota/plans/{connectionId}:
    get:
      tags: [Quota]
      summary: Get resolved plan for a connection
      security:
        - bearerAuth: []
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: ProviderPlan (source = auto | manual)
        "401":
          description: Unauthorized
        "404":
          description: Connection not found
        "500":
          description: Internal server error
    put:
      tags: [Quota]
      summary: Upsert manual plan override for a connection
      security:
        - bearerAuth: []
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PlanUpsert"
      responses:
        "200":
          description: Updated plan
        "400":
          description: Validation error (Zod)
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    delete:
      tags: [Quota]
      summary: Delete manual plan override (reverts to catalog/auto)
      security:
        - bearerAuth: []
      parameters:
        - name: connectionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Override deleted
        "401":
          description: Unauthorized
        "404":
          description: Override not found
        "500":
          description: Internal server error

  /api/quota/preview:
    get:
      tags: [Quota]
      summary: Dry-run quota enforcement check (preview only, no consumption recorded)
      security:
        - bearerAuth: []
      parameters:
        - name: apiKeyId
          in: query
          required: true
          schema:
            type: string
        - name: poolId
          in: query
          required: true
          schema:
            type: string
        - name: estimatedTokens
          in: query
          schema:
            type: number
        - name: estimatedUsd
          in: query
          schema:
            type: number
        - name: estimatedRequests
          in: query
          schema:
            type: integer
      responses:
        "200":
          description: EnforceDecision (allow/block + reason)
        "400":
          description: Validation error (Zod)
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  /api/settings/quota-store:
    get:
      tags: [Settings]
      summary: Get current quota store driver settings
      description: Redis URL is masked in the response (shows only scheme+host).
      security:
        - bearerAuth: []
      responses:
        "200":
          description: QuotaStoreSettings (driver + masked redisUrl)
        "401":
          description: Unauthorized
        "500":
          description: Internal server error
    put:
      tags: [Settings]
      summary: Update quota store driver settings
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QuotaStoreSettings"
      responses:
        "200":
          description: Settings updated
        "400":
          description: Validation error (Zod) — e.g. driver=redis without valid URL
        "401":
          description: Unauthorized
        "500":
          description: Internal server error

  # ─── v1beta (Gemini-Compatible) ─────────────────────────────────

  /api/v1beta/models:
    get:
      tags: [Models]
      summary: List models (Gemini format)
      description: Returns models in Gemini v1beta format for native SDK compatibility
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Model list in Gemini format

  /api/v1beta/models/{path}:
    post:
      tags: [Models]
      summary: Gemini generateContent
      description: Gemini-compatible generateContent endpoint
      security:
        - BearerAuth: []
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Generated content

  # ─── OpenAPI Spec ──────────────────────────────────────────────

  /api/openapi/spec:
    get:
      tags: [System]
      summary: Get OpenAPI specification catalog
      description: >-
        Returns a structured JSON catalog parsed from this `openapi.yaml`,
        including info, servers, tags, schemas, and a flat list of endpoints
        (method, path, tags, summary, security, parameters, responses).
        Used by the in-app API explorer.
      responses:
        "200":
          description: Parsed OpenAPI catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  info:
                    type: object
                  servers:
                    type: array
                    items:
                      type: object
                  tags:
                    type: array
                    items:
                      type: object
                  endpoints:
                    type: array
                    items:
                      type: object
                      properties:
                        method:
                          type: string
                        path:
                          type: string
                        tags:
                          type: array
                          items:
                            type: string
                        summary:
                          type: string
                        description:
                          type: string
                        security:
                          type: boolean
                        parameters:
                          type: array
                          items:
                            type: object
                        requestBody:
                          type: boolean
                        responses:
                          type: array
                          items:
                            type: string
                  schemas:
                    type: array
                    items:
                      type: string
        "404":
          description: openapi.yaml file not found on disk
        "500":
          description: Failed to parse OpenAPI spec

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from the OmniRoute dashboard
    ManagementSessionAuth:
      type: apiKey
      in: cookie
      name: auth_token
      description: Dashboard management session cookie for protected management routes

  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string

  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
    ManagementAuthenticationRequired:
      description: Authentication required for management routes
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          example:
            error:
              message: Authentication required
              type: invalid_request
            requestId: 3f9f6f5a-509a-4b35-b0a7-2d2d99d73a01
    ManagementInvalidToken:
      description: Bearer tokens are not accepted for management routes
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiErrorResponse"
          example:
            error:
              message: Invalid management token
              type: invalid_request
            requestId: 1b6a6ff8-d60c-4900-8d0a-25f81749f0a3
    ValidationError:
      description: Request body failed validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ValidationErrorResponse"

  schemas:
    QuotaPool:
      type: object
      description: A quota sharing pool — binds a provider connection to allocation rules.
      required: [id, connectionId, name, createdAt, allocations]
      properties:
        id:
          type: string
        connectionId:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        allocations:
          type: array
          items:
            $ref: "#/components/schemas/PoolAllocation"

    PoolAllocation:
      type: object
      required: [apiKeyId, weight, policy]
      properties:
        apiKeyId:
          type: string
        weight:
          type: number
          minimum: 0
          maximum: 100
          description: Share percentage (0–100)
        capValue:
          type: number
          nullable: true
          description: Absolute cap value (optional)
        capUnit:
          type: string
          enum: [percent, requests, tokens, usd]
          nullable: true
        policy:
          type: string
          enum: [hard, soft, burst]

    PoolCreate:
      type: object
      required: [connectionId, name]
      properties:
        connectionId:
          type: string
        name:
          type: string
          maxLength: 120
        allocations:
          type: array
          items:
            $ref: "#/components/schemas/PoolAllocation"
          default: []

    PoolUpdate:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        allocations:
          type: array
          items:
            $ref: "#/components/schemas/PoolAllocation"

    PoolUsageSnapshot:
      type: object
      required: [poolId, generatedAt, dimensions]
      properties:
        poolId:
          type: string
        generatedAt:
          type: string
          format: date-time
        dimensions:
          type: array
          items:
            type: object
            properties:
              unit:
                type: string
                enum: [percent, requests, tokens, usd]
              window:
                type: string
                enum: ["5h", hourly, daily, weekly, monthly]
              limit:
                type: number
              consumedTotal:
                type: number
              perKey:
                type: array
                items:
                  type: object
                  properties:
                    apiKeyId:
                      type: string
                    consumed:
                      type: number
                    fairShare:
                      type: number
                    deficit:
                      type: number
                      description: "Negative = surplus; positive = over-allocation"
                    borrowing:
                      type: boolean
        burnRate:
          type: object
          nullable: true
          properties:
            tokensPerSecond:
              type: number
            timeToExhaustionMs:
              type: number
              nullable: true

    QuotaDimension:
      type: object
      required: [unit, window, limit]
      properties:
        unit:
          type: string
          enum: [percent, requests, tokens, usd]
        window:
          type: string
          enum: ["5h", hourly, daily, weekly, monthly]
        limit:
          type: number
          minimum: 0

    PlanUpsert:
      type: object
      required: [dimensions]
      properties:
        dimensions:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/QuotaDimension"

    QuotaStoreSettings:
      type: object
      required: [driver]
      properties:
        driver:
          type: string
          enum: [sqlite, redis]
        redisUrl:
          type: string
          format: uri
          nullable: true
          description: Redis connection URL (write-only; masked in GET responses)

    ServiceStatus:
      type: object
      description: Live supervisor state for an embedded service
      properties:
        tool:
          type: string
          example: 9router
        state:
          type: string
          enum: [not_installed, stopped, starting, running, stopping, error]
        pid:
          type: integer
          nullable: true
        port:
          type: integer
          example: 20130
        health:
          type: string
          enum: [unknown, healthy, degraded]
        startedAt:
          type: string
          format: date-time
          nullable: true
        lastError:
          type: string
          nullable: true

    ServiceStatusExtended:
      allOf:
        - $ref: "#/components/schemas/ServiceStatus"
        - type: object
          description: >-
            Extended status including version metadata and (for 9Router) API key preview.
          properties:
            installedVersion:
              type: string
              nullable: true
            latestVersion:
              type: string
              nullable: true
            updateAvailable:
              type: boolean
            apiKeyMasked:
              type: string
              nullable: true
              description: >-
                Masked API key preview (e.g. "nr_****abcd").
                Present only for services that use an injected API key (9Router).
            autoStart:
              type: boolean
            providerExpose:
              type: boolean
              description: >-
                Whether models from this service are exposed as a routing provider.
                9Router only.

    ApiErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            details:
              description: Optional additional error details
        requestId:
          type: string
          format: uuid

    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: object
          required: [message, details]
          properties:
            message:
              type: string
              example: Invalid request
            details:
              type: array
              items:
                type: object
                required: [field, message]
                properties:
                  field:
                    type: string
                  message:
                    type: string

    PayloadRuleModelSpec:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
        protocol:
          type: string
          minLength: 1

    PayloadMutationRule:
      type: object
      additionalProperties: false
      required: [models, params]
      properties:
        models:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/PayloadRuleModelSpec"
        params:
          type: object
          minProperties: 1
          additionalProperties: true

    PayloadFilterRule:
      type: object
      additionalProperties: false
      required: [models, params]
      properties:
        models:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/PayloadRuleModelSpec"
        params:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1

    PayloadRulesConfig:
      type: object
      additionalProperties: false
      required: [default, override, filter, defaultRaw]
      properties:
        default:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
        override:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
        filter:
          type: array
          items:
            $ref: "#/components/schemas/PayloadFilterRule"
        defaultRaw:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"

    UpdatePayloadRulesRequest:
      type: object
      additionalProperties: false
      description: At least one payload-rules section must be present in the request body.
      properties:
        default:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
        override:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
        filter:
          type: array
          items:
            $ref: "#/components/schemas/PayloadFilterRule"
        defaultRaw:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
        default-raw:
          type: array
          items:
            $ref: "#/components/schemas/PayloadMutationRule"
      anyOf:
        - required: [default]
        - required: [override]
        - required: [filter]
        - required: [defaultRaw]
        - required: [default-raw]

    ChatCompletionRequest:
      type: object
      required: [model, messages]
      properties:
        model:
          type: string
          example: gpt-4o
        messages:
          type: array
          items:
            type: object
            required: [role]
            properties:
              role:
                type: string
                description: >-
                  Message role. The proxy accepts any non-empty string; common values
                  include system, user, assistant, tool, function, and developer.
                example: user
              content:
                description: >-
                  Message content. May be a plain string, an array of content parts
                  for multimodal inputs (text, image, audio, etc.), or null when the
                  message only carries tool/function calls.
                oneOf:
                  - type: string
                  - type: array
                    items:
                      type: object
                  - type: "null"
              name:
                type: string
              tool_call_id:
                type: string
              tool_calls:
                type: array
                items:
                  type: object
              function_call:
                type: object
        stream:
          type: boolean
          default: false
        temperature:
          type: number
          minimum: 0
          maximum: 2
        max_tokens:
          type: integer
        top_p:
          type: number
          minimum: 0
          maximum: 1
        n:
          type: integer
          minimum: 1
          default: 1
        stop:
          description: Up to 4 stop sequences (string or array of strings).
          oneOf:
            - type: string
            - type: array
              items:
                type: string
              maxItems: 4
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
        seed:
          type: integer
        logprobs:
          type: boolean
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
        response_format:
          type: object
          description: Output format constraint (e.g. JSON mode or JSON Schema).
          properties:
            type:
              type: string
              example: json_object
        tools:
          type: array
          description: Tool definitions available to the model.
          items:
            type: object
        tool_choice:
          description: Controls which tool (if any) is invoked by the model.
          oneOf:
            - type: string
              example: auto
            - type: object
        parallel_tool_calls:
          type: boolean
          default: true
        service_tier:
          type: string
          example: auto
        user:
          type: string
          description: Stable end-user identifier for abuse monitoring.

    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer

    MessagesRequest:
      type: object
      required: [model, messages, max_tokens]
      properties:
        model:
          type: string
          example: claude-sonnet-4-5-20250514
        messages:
          type: array
          items:
            type: object
            required: [role, content]
            properties:
              role:
                type: string
                enum: [user, assistant]
              content:
                type: string
        max_tokens:
          type: integer
        stream:
          type: boolean
          default: false
        system:
          type: string

    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: model
        owned_by:
          type: string

    ProviderConnection:
      type: object
      properties:
        id:
          type: string
        provider:
          type: string
        name:
          type: string
        url:
          type: string
        isActive:
          type: boolean
        maxConcurrent:
          type: integer
          nullable: true
          minimum: 0
        priority:
          type: integer
        testStatus:
          type: string
          enum: [active, error, untested]
        createdAt:
          type: string
          format: date-time

    ProviderConnectionCreate:
      type: object
      required: [provider, url]
      properties:
        provider:
          type: string
          example: openai
        name:
          type: string
        url:
          type: string
        apiKey:
          type: string
        isActive:
          type: boolean
          default: true
        maxConcurrent:
          type: integer
          nullable: true
          minimum: 0

    ApiKey:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        keyPreview:
          type: string
          description: Last 4 characters of the key
        isActive:
          type: boolean
        createdAt:
          type: string
          format: date-time

    ComboCreate:
      type: object
      required: [name, model]
      properties:
        name:
          type: string
        model:
          type: string
        strategy:
          type: string
          enum:
            - priority
            - weighted
            - round-robin
            - context-relay
            - fill-first
            - p2c
            - random
            - least-used
            - cost-optimized
            - reset-aware
            - strict-random
            - auto
            - lkgp
            - context-optimized
          default: priority
        nodes:
          type: array
          items:
            type: object
            properties:
              connectionId:
                type: string
              weight:
                type: integer
              priority:
                type: integer