openapi: 3.1.0
info:
  title: OmniRoute API
  version: 3.8.4
  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

# Vendor extensions — OmniRoute security tier annotations (OpenAPI 3.x compatible)
x-tier-definitions:
  loopback-only:
    description: "Route is enforced as loopback-only (127.0.0.1, ::1) regardless of auth.
      Cannot be authenticated remotely. Spawn-capable routes are classified here.
      Reference: docs/security/ROUTE_GUARD_TIERS.md"
  always-protected:
    description: "Route requires authentication unconditionally, even when REQUIRE_API_KEY=false.
      Destructive/irreversible operations are classified here.
      Reference: docs/security/ROUTE_GUARD_TIERS.md"
  internal:
    description: "Internal route not part of the public API surface.
      Hidden from /dashboard/api-endpoints by default."

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: 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
  - name: MCP
    description: Model Context Protocol server (LOCAL_ONLY — loopback access only)
  - name: Webhooks
    description: Webhook endpoint management and testing
  - name: Tunnels
    description: Tunnel (ngrok, Cloudflare, Tailscale) management
  - name: Skills
    description: Skill framework — install, list, execute
  - name: Memory
    description: Persistent conversational memory (FTS5 + Qdrant)
  - name: Logs
    description: Application and request log access
  - name: Version Manager
    description: Version check and update management
  - name: Analytics
    description: Internal analytics and routing statistics
  - name: A2A
    description: Agent-to-Agent JSON-RPC 2.0 protocol
  - name: Evals
    description: Evaluation suites
  - name: Files
    description: File uploads and management
  - name: Batches
    description: Batch request processing

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/responses/{...path}:
    get:
      tags: [Responses]
      summary: Responses API catch-all (GET)
      description: Generic Responses API passthrough for sub-paths.
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Responses API result
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Responses]
      summary: Responses API catch-all (POST)
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Responses API result
        "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/settings/database:
    get:
      tags: [Settings]
      summary: Get database settings
      description: Returns SQLite database configuration (WAL mode, journal, paths).
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Database settings
        "401":
          $ref: "#/components/responses/Unauthorized"
    patch:
      tags: [Settings]
      summary: Update database settings
      description: Updates SQLite WAL or journal mode settings. Requires restart to take effect.
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Settings]
      summary: Update database settings (alias for PATCH)
      description: >-
        Alias for PATCH /api/settings/database. Updates SQLite WAL or journal mode
        settings. Requires restart to take effect.
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/settings/database/refresh-stats:
    post:
      tags: [Settings]
      summary: Refresh database statistics
      description: Runs ANALYZE to refresh SQLite query planner statistics.
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Stats refreshed
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/settings/database/vacuum:
    post:
      tags: [Settings]
      summary: Vacuum database
      description: Runs VACUUM FULL on the SQLite database to reclaim disk space. Destructive — cannot be interrupted.
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Vacuum completed
        "401":
          $ref: "#/components/responses/Unauthorized"

  /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
      description: >-
        Gets runtime status for a CLI tool.
        LOCAL_ONLY — spawn-capable route, blocked unconditionally from non-loopback.
        CVE class: GHSA-fhh6-4qxv-rpqj.
      x-loopback-only: true
      parameters:
        - name: toolId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Runtime status
        "403":
          description: Forbidden — request not from loopback

  /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

  /api/cli-tools/apply:
    post:
      tags: [CLI Tools]
      summary: Apply CLI tool configuration
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Configuration applied
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/config:
    get:
      tags: [CLI Tools]
      summary: Get CLI tools global configuration
      x-internal: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: CLI tools configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [CLI Tools]
      summary: Update CLI tools global configuration
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Configuration updated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/detect:
    get:
      tags: [CLI Tools]
      summary: Detect locally installed CLI tools
      description: Scans the local system and returns a map of detected CLI tools and their versions.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Map of detected tools with version info
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/hermes-agent-settings:
    get:
      tags: [CLI Tools]
      summary: Get Hermes agent CLI settings
      x-internal: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Hermes agent CLI configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [CLI Tools]
      summary: Apply Hermes agent CLI settings
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Hermes agent CLI settings applied
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/keys:
    get:
      tags: [CLI Tools]
      summary: Get CLI tool API keys
      x-internal: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: CLI tool API key configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [CLI Tools]
      summary: Set CLI tool API keys
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: CLI tool API keys updated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/openclaw/auto-order:
    get:
      tags: [CLI Tools]
      summary: Get OpenClaw auto-order configuration
      x-internal: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: OpenClaw auto-order configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [CLI Tools]
      summary: Update OpenClaw auto-order configuration
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: OpenClaw auto-order configuration updated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/qwen-settings:
    get:
      tags: [CLI Tools]
      summary: Get Qwen CLI settings
      x-internal: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Qwen CLI configuration
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [CLI Tools]
      summary: Apply Qwen CLI settings
      x-internal: true
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Qwen CLI settings applied
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/cli-tools/status:
    get:
      tags: [CLI Tools]
      summary: CLI tools service status
      description: Returns health and status of the CLI tools subsystem.
      security:
        - BearerAuth: []
      responses:
        "200":
          description: CLI tools status
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/upstream-proxy/{providerId}:
    get:
      tags: [Internal]
      summary: Upstream proxy passthrough (GET)
      description: Proxies GET requests to the upstream provider. Internal use only.
      x-internal: true
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Proxied response from upstream provider
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Internal]
      summary: Upstream proxy passthrough (POST)
      x-internal: true
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Proxied response from upstream provider
        "401":
          $ref: "#/components/responses/Unauthorized"
    put:
      tags: [Internal]
      summary: Upstream proxy passthrough (PUT)
      x-internal: true
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Proxied response from upstream provider
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Internal]
      summary: Upstream proxy passthrough (DELETE)
      x-internal: true
      parameters:
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Proxied response from upstream provider
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ─── MCP Server (LOCAL_ONLY — spawn-capable) ─────────────────────
  # These routes start/control the MCP server subprocess. They are
  # enforced as loopback-only by routeGuard.ts regardless of auth state.
  # CVE class: GHSA-fhh6-4qxv-rpqj — never expose to non-loopback traffic.

  /api/mcp/sse:
    get:
      tags: [MCP]
      summary: MCP Server-Sent Events stream
      description: >-
        SSE transport for the MCP server. Streams tool call results and events.
        LOCAL_ONLY — blocked unconditionally from non-loopback IPs.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: SSE event stream
          content:
            text/event-stream:
              schema:
                type: string
        "403":
          description: Forbidden — request not from loopback

  /api/mcp/stream:
    get:
      tags: [MCP]
      summary: MCP HTTP streaming transport
      description: >-
        HTTP streaming (chunked) transport for the MCP server.
        LOCAL_ONLY — blocked unconditionally from non-loopback IPs.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Chunked stream
        "403":
          description: Forbidden — request not from loopback
    post:
      tags: [MCP]
      summary: MCP HTTP streaming transport (POST)
      description: >-
        HTTP streaming (chunked) transport for the MCP server — POST variant.
        LOCAL_ONLY — blocked unconditionally from non-loopback IPs.
      x-loopback-only: true
      security:
        - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: MCP response
        "403":
          description: Forbidden — request not from loopback

  /api/mcp/status:
    get:
      tags: [MCP]
      summary: MCP server status
      description: Returns running/stopped state of the MCP server process. LOCAL_ONLY.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: MCP server status object
        "403":
          description: Forbidden — request not from loopback

  /api/mcp/tools:
    get:
      tags: [MCP]
      summary: List MCP tools
      description: Returns the registered tool manifest. LOCAL_ONLY.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Tool list
        "403":
          description: Forbidden — request not from loopback

  /api/mcp/audit:
    get:
      tags: [MCP]
      summary: MCP audit log
      description: Returns recent MCP tool invocation log entries. LOCAL_ONLY.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Audit log entries
        "403":
          description: Forbidden — request not from loopback

  /api/mcp/audit/stats:
    get:
      tags: [MCP]
      summary: MCP audit statistics
      description: Returns aggregate MCP tool usage statistics. LOCAL_ONLY.
      x-loopback-only: true
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Audit stats
        "403":
          description: Forbidden — request not from loopback

  # ─── 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

  # ─── Webhooks ─────────────────────────────────────────────────────

  /api/webhooks:
    get:
      tags: [Webhooks]
      summary: List webhooks
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Webhook list
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Webhooks]
      summary: Create webhook
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                events:
                  type: array
                  items:
                    type: string
                secret:
                  type: string
      responses:
        "201":
          description: Webhook created
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/webhooks/{id}:
    get:
      tags: [Webhooks]
      summary: Get webhook
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Webhook details
        "404":
          description: Not found
        "401":
          $ref: "#/components/responses/Unauthorized"
    patch:
      tags: [Webhooks]
      summary: Update webhook
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Webhook updated
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Webhooks]
      summary: Delete webhook
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Webhook deleted
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/webhooks/{id}/test:
    post:
      tags: [Webhooks]
      summary: Test webhook delivery
      description: Sends a test event payload to the webhook URL.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Test delivery result
        "401":
          $ref: "#/components/responses/Unauthorized"

  # ─── Tunnels ──────────────────────────────────────────────────────

  /api/tunnels/ngrok:
    get:
      tags: [Tunnels]
      summary: Get ngrok tunnel status
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: ngrok tunnel status
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Tunnels]
      summary: Start/configure ngrok tunnel
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Tunnel started
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Tunnels]
      summary: Stop ngrok tunnel
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Tunnel stopped

  /api/tunnels/cloudflared:
    get:
      tags: [Tunnels]
      summary: Get Cloudflare Tunnel status
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Cloudflare tunnel status
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Tunnels]
      summary: Start/configure Cloudflare Tunnel
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Tunnel started
    delete:
      tags: [Tunnels]
      summary: Stop Cloudflare Tunnel
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Tunnel stopped

  /api/tunnels/tailscale:
    get:
      tags: [Tunnels]
      summary: Get Tailscale status
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Tailscale status
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/tunnels/tailscale/install:
    post:
      tags: [Tunnels]
      summary: Install Tailscale
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Install initiated

  /api/tunnels/tailscale/login:
    post:
      tags: [Tunnels]
      summary: Tailscale login / auth key
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                authKey:
                  type: string
      responses:
        "200":
          description: Login result

  /api/tunnels/tailscale/start-daemon:
    post:
      tags: [Tunnels]
      summary: Start Tailscale daemon
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Daemon started

  /api/tunnels/tailscale/enable:
    post:
      tags: [Tunnels]
      summary: Enable Tailscale routing
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Routing enabled

  /api/tunnels/tailscale/disable:
    post:
      tags: [Tunnels]
      summary: Disable Tailscale routing
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Routing disabled

  /api/tunnels/tailscale/check:
    get:
      tags: [Tunnels]
      summary: Check Tailscale connectivity
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Connectivity check result

  # ─── Skills ───────────────────────────────────────────────────────

  /api/skills:
    get:
      tags: [Skills]
      summary: List installed skills
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Skill list
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/skills/{id}:
    get:
      tags: [Skills]
      summary: Get skill details
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Skill details
        "404":
          description: Skill not found
        "401":
          $ref: "#/components/responses/Unauthorized"
    delete:
      tags: [Skills]
      summary: Uninstall skill
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Skill uninstalled

  /api/skills/install:
    post:
      tags: [Skills]
      summary: Install skill from ZIP or URL
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                source:
                  type: string
                  description: URL or base64 ZIP
      responses:
        "201":
          description: Skill installed
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/skills/marketplace:
    get:
      tags: [Skills]
      summary: Browse skill marketplace
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Available skills

  /api/skills/marketplace/install:
    post:
      tags: [Skills]
      summary: Install skill from marketplace
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                skillId:
                  type: string
      responses:
        "201":
          description: Skill installed

  /api/skills/executions:
    get:
      tags: [Skills]
      summary: List skill execution history
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Execution history

  # ─── 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 OmniRoute service
      description: >-
        Initiates a graceful shutdown. Always requires authentication regardless of
        the `requireLogin` setting — classified as ALWAYS_PROTECTED in routeGuard.ts.
      x-always-protected: true
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "202":
          description: Shutdown initiated
        "401":
          $ref: "#/components/responses/Unauthorized"

  /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/db-backups/export:
    post:
      tags: [System]
      summary: Export database to file
      description: Creates a snapshot export of the SQLite database.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Export file path or download
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/db-backups/exportAll:
    post:
      tags: [System]
      summary: Export all data to ZIP
      description: Exports the full database including attachments to a ZIP archive.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: ZIP archive
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/db-backups/import:
    post:
      tags: [System]
      summary: Import database from backup
      description: >-
        Restores database from a backup file. Destructive — overwrites current data.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Import successful
        "401":
          $ref: "#/components/responses/Unauthorized"

  /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
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        "200":
          description: Audit log entries

  # ─── 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

  # ─── Memory ───────────────────────────────────────────────────────

  /api/memory:
    get:
      tags: [Memory]
      summary: List memory entries
      description: Returns conversational memory entries (FTS5 + Qdrant).
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Memory entries
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Memory]
      summary: Create memory entry
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
      responses:
        "201":
          description: Memory entry created
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/memory/{id}:
    get:
      tags: [Memory]
      summary: Get memory entry
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Memory entry
        "404":
          description: Not found
    patch:
      tags: [Memory]
      summary: Update memory entry
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Memory entry updated
    delete:
      tags: [Memory]
      summary: Delete memory entry
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Memory entry deleted

  /api/memory/health:
    get:
      tags: [Memory]
      summary: Memory system health
      description: Returns health of FTS5 index and Qdrant vector store.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Memory health status

  # ─── Logs ─────────────────────────────────────────────────────────

  /api/logs/console:
    get:
      tags: [Logs]
      summary: Get application console logs
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Console log entries
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/logs/active:
    get:
      tags: [Logs]
      summary: Get active request logs
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Active request log entries

  /api/logs/detail:
    get:
      tags: [Logs]
      summary: Get detailed log entries
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: query
          schema:
            type: string
      responses:
        "200":
          description: Detailed log entry

  /api/logs/export:
    get:
      tags: [Logs]
      summary: Export logs as file
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Log file download

  # ─── v1 Missing Routes ────────────────────────────────────────────

  /api/v1/completions:
    post:
      tags: [Chat]
      summary: Legacy completions (text)
      description: OpenAI legacy text completions endpoint.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Completion response

  /api/v1/batches:
    get:
      tags: [Batches]
      summary: List batch jobs
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Batch job list
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Batches]
      summary: Create batch job
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Batch job created

  /api/v1/batches/{id}:
    get:
      tags: [Batches]
      summary: Get batch job
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch job details
    delete:
      tags: [Batches]
      summary: Cancel batch job
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch cancelled

  /api/v1/batches/{id}/cancel:
    post:
      tags: [Batches]
      summary: Cancel batch job (explicit)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch cancelled

  /api/v1/files:
    get:
      tags: [Files]
      summary: List uploaded files
      security:
        - BearerAuth: []
      responses:
        "200":
          description: File list
    post:
      tags: [Files]
      summary: Upload file
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                purpose:
                  type: string
      responses:
        "201":
          description: File uploaded

  /api/v1/files/{id}:
    get:
      tags: [Files]
      summary: Get file metadata
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File metadata
    delete:
      tags: [Files]
      summary: Delete file
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File deleted

  /api/v1/files/{id}/content:
    get:
      tags: [Files]
      summary: Get file content
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content

  /api/v1/images/edits:
    post:
      tags: [Images]
      summary: Edit image
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "200":
          description: Edited image

  /api/v1/music/generations:
    post:
      tags: [Audio]
      summary: Generate music
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Generated music

  /api/v1/videos/generations:
    post:
      tags: [Images]
      summary: Generate video
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Generated video

  /api/v1/quotas/check:
    get:
      tags: [API Keys]
      summary: Check quota usage
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Quota status

  /api/v1/registered-keys:
    get:
      tags: [API Keys]
      summary: List registered API keys
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Registered keys
    post:
      tags: [API Keys]
      summary: Register API key
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Key registered

  /api/v1/registered-keys/{id}:
    get:
      tags: [API Keys]
      summary: Get registered key
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key details
    delete:
      tags: [API Keys]
      summary: Delete registered key
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key deleted

  /api/v1/registered-keys/{id}/revoke:
    post:
      tags: [API Keys]
      summary: Revoke registered key
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key revoked

  # ─── Usage Extensions ─────────────────────────────────────────────

  /api/usage/quota:
    get:
      tags: [Usage]
      summary: Get quota usage
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Quota usage stats

  /api/usage/utilization:
    get:
      tags: [Usage]
      summary: Get provider utilization metrics
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Utilization data

  /api/usage/combo-health:
    get:
      tags: [Usage]
      summary: Get combo health metrics
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Combo health metrics

  /api/usage/provider-limits:
    get:
      tags: [Usage]
      summary: Get provider rate limit status
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Provider limit status

  /api/usage/budget/bulk:
    patch:
      tags: [Usage]
      summary: Bulk update usage budgets
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Budgets updated

  # ─── Provider Extensions ──────────────────────────────────────────

  /api/providers/bulk:
    post:
      tags: [Providers]
      summary: Bulk provider operations
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk operation result

  /api/providers/{id}/refresh:
    post:
      tags: [Providers]
      summary: Refresh provider connection
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Provider refreshed

  /api/providers/{id}/sync-models:
    post:
      tags: [Providers]
      summary: Sync provider models
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Models synced

  /api/providers/expiration:
    get:
      tags: [Providers]
      summary: Get provider credential expiration status
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Expiration status

  /api/providers/quota-windows:
    get:
      tags: [Providers]
      summary: Get provider quota windows
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Quota window data

  # ─── Settings Extensions ──────────────────────────────────────────

  /api/settings/feature-flags:
    get:
      tags: [Settings]
      summary: Get feature flags
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Feature flags
    patch:
      tags: [Settings]
      summary: Update feature flags
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Flags updated

  /api/settings/memory:
    get:
      tags: [Settings]
      summary: Get memory settings
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Memory settings
    patch:
      tags: [Settings]
      summary: Update memory settings
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  /api/settings/model-aliases:
    get:
      tags: [Settings]
      summary: Get model aliases
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Model alias map
    post:
      tags: [Settings]
      summary: Create model alias
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Alias created
    delete:
      tags: [Settings]
      summary: Delete model alias
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Alias deleted

  /api/settings/export-json:
    get:
      tags: [Settings]
      summary: Export settings as JSON
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Settings JSON export

  /api/settings/import-json:
    post:
      tags: [Settings]
      summary: Import settings from JSON
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings imported

  /api/settings/purge-call-logs:
    post:
      tags: [Settings]
      summary: Purge call logs
      description: Deletes all call log records. Destructive.
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Logs purged

  /api/settings/purge-logs:
    post:
      tags: [Settings]
      summary: Purge all logs
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Logs purged

  /api/settings/cache-config:
    get:
      tags: [Settings]
      summary: Get cache configuration
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Cache config
    patch:
      tags: [Settings]
      summary: Update cache configuration
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Config updated

  /api/settings/task-routing:
    get:
      tags: [Settings]
      summary: Get task routing settings
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Task routing config
    patch:
      tags: [Settings]
      summary: Update task routing settings
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  # ─── Internal Routes (x-internal: true — hidden from dashboard by default) ─

  /api/analytics/auto-routing:
    get:
      tags: [Analytics]
      x-internal: true
      summary: Auto-routing decision analytics
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Auto-routing analytics

  /api/analytics/compression:
    get:
      tags: [Analytics]
      x-internal: true
      summary: Compression analytics
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Compression analytics

  /api/analytics/diversity:
    get:
      tags: [Analytics]
      x-internal: true
      summary: Provider diversity analytics
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Diversity analytics

  /api/assess:
    post:
      tags: [System]
      x-internal: true
      summary: Assess request (internal)
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Assessment result

  /api/admin/concurrency:
    get:
      tags: [System]
      x-internal: true
      summary: Admin concurrency status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Concurrency info

  /api/copilot/chat:
    post:
      tags: [Chat]
      x-internal: true
      summary: Copilot chat relay (internal)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Chat response

  /api/gamification/leaderboard:
    get:
      tags: [System]
      x-internal: true
      summary: Local gamification leaderboard
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Leaderboard

  /api/gamification/federation/leaderboard:
    get:
      tags: [System]
      x-internal: true
      summary: Federated gamification leaderboard
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Federation leaderboard

  /api/gamification/federation/score:
    post:
      tags: [System]
      x-internal: true
      summary: Submit federation score
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Score submitted

  /api/gamification/anomalies:
    get:
      tags: [System]
      x-internal: true
      summary: Gamification anomaly detection
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Anomaly data

  /api/gamification/invite:
    get:
      tags: [System]
      x-internal: true
      summary: Get invite code
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Invite code
    post:
      tags: [System]
      x-internal: true
      summary: Create invite
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Invite created

  /api/gamification/invite/redeem:
    post:
      tags: [System]
      x-internal: true
      summary: Redeem invite code
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Invite redeemed

  /api/gamification/notifications:
    get:
      tags: [System]
      x-internal: true
      summary: Gamification notifications
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Notifications

  /api/gamification/rotate:
    post:
      tags: [System]
      x-internal: true
      summary: Rotate gamification key
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Key rotated

  /api/gamification/servers:
    get:
      tags: [System]
      x-internal: true
      summary: Gamification server list
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Server list

  /api/gamification/stream:
    get:
      tags: [System]
      x-internal: true
      summary: Gamification event stream
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: SSE stream

  /api/gamification/transfer:
    post:
      tags: [System]
      x-internal: true
      summary: Transfer gamification data
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Transfer result

  /api/health/degradation:
    get:
      tags: [System]
      x-internal: true
      summary: Degradation health check
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Degradation status

  /api/network/info:
    get:
      tags: [System]
      x-internal: true
      summary: Network info
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Network info

  /api/playground/simulate-route:
    post:
      tags: [System]
      x-internal: true
      summary: Simulate routing decision (playground)
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Routing simulation result

  /api/provider-metrics:
    get:
      tags: [Providers]
      x-internal: true
      summary: Raw provider performance metrics
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Metrics

  /api/relay/tokens:
    get:
      tags: [System]
      x-internal: true
      summary: List relay tokens
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Relay tokens
    post:
      tags: [System]
      x-internal: true
      summary: Create relay token
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Token created

  /api/relay/tokens/{id}:
    delete:
      tags: [System]
      x-internal: true
      summary: Delete relay token
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Token deleted

  /api/search/providers:
    get:
      tags: [Providers]
      x-internal: true
      summary: Search providers (internal)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Search results

  /api/search/stats:
    get:
      tags: [System]
      x-internal: true
      summary: Search subsystem stats
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Stats

  /api/sync/bundle:
    get:
      tags: [System]
      x-internal: true
      summary: Get sync bundle
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Sync bundle

  /api/sync/tokens:
    get:
      tags: [System]
      x-internal: true
      summary: List sync tokens
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Sync tokens
    post:
      tags: [System]
      x-internal: true
      summary: Create sync token
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Token created

  /api/sync/tokens/{id}:
    delete:
      tags: [System]
      x-internal: true
      summary: Delete sync token
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Token deleted

  /api/synced-available-models:
    get:
      tags: [Models]
      x-internal: true
      summary: Synced available models (internal cache)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Model list

  /api/system/env/repair:
    post:
      tags: [System]
      x-internal: true
      summary: Repair environment configuration
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Repair result

  /api/system/version:
    get:
      tags: [System]
      x-internal: true
      summary: Get system version info
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Version info

  /api/v1/accounts/{id}/limits:
    get:
      tags: [API Keys]
      x-internal: true
      summary: Get account limits (internal)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Account limits

  /api/v1/agents/credentials:
    get:
      tags: [A2A]
      x-internal: true
      summary: Get agent credentials
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Agent credentials
    post:
      tags: [A2A]
      x-internal: true
      summary: Create agent credentials
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Credentials created

  /api/v1/agents/health:
    get:
      tags: [A2A]
      x-internal: true
      summary: Agent health check
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Agent health

  /api/v1/agents/tasks:
    get:
      tags: [A2A]
      x-internal: true
      summary: List agent tasks
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Agent tasks
    post:
      tags: [A2A]
      x-internal: true
      summary: Create agent task
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Task created

  /api/v1/agents/tasks/{id}:
    get:
      tags: [A2A]
      x-internal: true
      summary: Get agent task
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task details
    patch:
      tags: [A2A]
      x-internal: true
      summary: Update agent task
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Task updated

  /api/v1/batches/delete-completed:
    post:
      tags: [Batches]
      x-internal: true
      summary: Delete completed batch jobs
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Completed batches deleted

  /api/v1/chatgpt-web/image/{id}:
    get:
      tags: [Images]
      x-internal: true
      summary: Retrieve ChatGPT web image (internal)
      security:
        - BearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Image data

  /api/v1/combos:
    get:
      tags: [Combos]
      x-internal: true
      summary: List combos (v1 proxy)
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Combo list

  /api/v1/issues/report:
    post:
      tags: [System]
      x-internal: true
      summary: Submit issue report
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Issue reported

  /api/v1/management/proxies:
    get:
      tags: [Providers]
      x-internal: true
      summary: Management proxy list
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Proxy list
    post:
      tags: [Providers]
      x-internal: true
      summary: Create management proxy
      security:
        - BearerAuth: []
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Proxy created

  /api/v1/management/proxies/assignments:
    get:
      tags: [Providers]
      x-internal: true
      summary: List proxy assignments
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Assignments

  /api/v1/management/proxies/bulk-assign:
    post:
      tags: [Providers]
      x-internal: true
      summary: Bulk assign proxies
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk assignment result

  /api/v1/management/proxies/health:
    get:
      tags: [Providers]
      x-internal: true
      summary: Management proxy health
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Health status

  /api/v1/providers/{provider}/limits:
    get:
      tags: [Providers]
      x-internal: true
      summary: Get provider-specific rate limits (v1)
      security:
        - BearerAuth: []
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Rate limits

  /api/v1/relay/chat/completions:
    post:
      tags: [Chat]
      x-internal: true
      summary: Relay chat completions (internal)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Relay response

  /api/v1/search:
    get:
      tags: [System]
      x-internal: true
      summary: Internal search endpoint
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Search results

  /api/v1/search/analytics:
    get:
      tags: [Analytics]
      x-internal: true
      summary: Search analytics
      security:
        - BearerAuth: []
      responses:
        "200":
          description: Search analytics

  /api/v1/web/fetch:
    post:
      tags: [System]
      x-internal: true
      summary: Web fetch proxy (internal)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Fetched content

  /api/v1/ws:
    get:
      tags: [System]
      x-internal: true
      summary: WebSocket upgrade endpoint
      security:
        - BearerAuth: []
      responses:
        "101":
          description: WebSocket upgrade

  /api/version-manager/status:
    get:
      tags: [Version Manager]
      x-internal: true
      summary: Version manager status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Version manager state

  /api/version-manager/check-update:
    get:
      tags: [Version Manager]
      x-internal: true
      summary: Check for updates
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Update availability

  /api/version-manager/install:
    post:
      tags: [Version Manager]
      x-internal: true
      summary: Install update
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Install initiated

  /api/version-manager/start:
    post:
      tags: [Version Manager]
      x-internal: true
      summary: Start version manager
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Started

  /api/version-manager/stop:
    post:
      tags: [Version Manager]
      x-internal: true
      summary: Stop version manager
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Stopped

  /api/version-manager/restart:
    post:
      tags: [Version Manager]
      x-internal: true
      summary: Restart version manager
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Restarted

  /api/models/openrouter-catalog:
    get:
      tags: [Models]
      x-internal: true
      summary: OpenRouter model catalog (cached)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Model catalog

  /api/models/test:
    post:
      tags: [Models]
      x-internal: true
      summary: Test model routing
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Test result

  /api/cache/entries:
    get:
      tags: [System]
      x-internal: true
      summary: List cache entries
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Cache entries

  /api/cache/reasoning:
    get:
      tags: [System]
      x-internal: true
      summary: Reasoning cache entries
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Reasoning cache

  /api/context/analytics:
    get:
      tags: [Settings]
      x-internal: true
      summary: Context analytics
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Context analytics

  /api/context/caveman/config:
    get:
      tags: [Settings]
      x-internal: true
      summary: Caveman context config
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Config
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update caveman context config
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Config updated

  /api/context/combos:
    get:
      tags: [Settings]
      x-internal: true
      summary: List context combos
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Context combos
    post:
      tags: [Settings]
      x-internal: true
      summary: Create context combo
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Combo created

  /api/context/combos/{id}:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get context combo
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Context combo
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update context combo
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Combo updated
    delete:
      tags: [Settings]
      x-internal: true
      summary: Delete context combo
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Combo deleted

  /api/context/combos/{id}/assignments:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get context combo assignments
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Assignments
    post:
      tags: [Settings]
      x-internal: true
      summary: Update context combo assignments
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Assignments updated

  /api/middleware/hooks:
    get:
      tags: [Settings]
      x-internal: true
      summary: List middleware hooks
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Hook list
    post:
      tags: [Settings]
      x-internal: true
      summary: Create middleware hook
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Hook created

  /api/middleware/hooks/{name}:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get middleware hook
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Hook details
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update middleware hook
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Hook updated
    delete:
      tags: [Settings]
      x-internal: true
      summary: Delete middleware hook
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Hook deleted

  /api/settings/auto-disable-accounts:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get auto-disable accounts settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Auto-disable settings
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update auto-disable accounts settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  /api/settings/background-degradation:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get background degradation settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Degradation settings
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update background degradation settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  /api/settings/authz-inventory:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get authorization inventory
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Authz inventory

  /api/settings/cache-metrics:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get cache performance metrics
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Cache metrics

  /api/settings/favicon:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get custom favicon setting
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Favicon config
    post:
      tags: [Settings]
      x-internal: true
      summary: Update custom favicon
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "200":
          description: Favicon updated

  /api/settings/lkgp-cache:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get LKGP cache state
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: LKGP cache state
    delete:
      tags: [Settings]
      x-internal: true
      summary: Clear LKGP cache
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Cache cleared

  /api/settings/mitm:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get MITM proxy settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: MITM settings
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update MITM proxy settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  /api/settings/models-dev:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get dev model overrides
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Dev model overrides
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update dev model overrides
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Overrides updated

  /api/settings/oneproxy:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get OneProxy settings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: OneProxy settings
    patch:
      tags: [Settings]
      x-internal: true
      summary: Update OneProxy settings
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Settings updated

  /api/settings/oneproxy/rotate:
    post:
      tags: [Settings]
      x-internal: true
      summary: Rotate OneProxy credentials
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Credentials rotated

  /api/settings/proxies:
    get:
      tags: [Settings]
      x-internal: true
      summary: List proxy configurations
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Proxy configurations
    post:
      tags: [Settings]
      x-internal: true
      summary: Create proxy configuration
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Proxy created

  /api/settings/proxies/assignments:
    get:
      tags: [Settings]
      x-internal: true
      summary: List proxy assignments
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Proxy assignments
    post:
      tags: [Settings]
      x-internal: true
      summary: Update proxy assignments
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Assignments updated

  /api/settings/proxies/bulk-assign:
    post:
      tags: [Settings]
      x-internal: true
      summary: Bulk assign proxies
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk assignment result

  /api/settings/proxies/bulk-import:
    post:
      tags: [Settings]
      x-internal: true
      summary: Bulk import proxy configurations
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/settings/proxies/health:
    get:
      tags: [Settings]
      x-internal: true
      summary: Proxy configuration health check
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Health status

  /api/settings/proxies/migrate:
    post:
      tags: [Settings]
      x-internal: true
      summary: Migrate proxy configurations
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Migration result

  /api/settings/purge-detailed-logs:
    post:
      tags: [Settings]
      x-internal: true
      summary: Purge detailed logs
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Logs purged

  /api/settings/purge-quota-snapshots:
    post:
      tags: [Settings]
      x-internal: true
      summary: Purge quota snapshots
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Snapshots purged

  /api/settings/qdrant/embedding-models:
    get:
      tags: [Settings]
      x-internal: true
      summary: List Qdrant embedding models
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Embedding model list

  /api/settings/compression/rules:
    get:
      tags: [Settings]
      x-internal: true
      summary: Get compression rules (settings sub-path)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Compression rules

  /api/keys/groups:
    get:
      tags: [API Keys]
      x-internal: true
      summary: List API key groups
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Key groups
    post:
      tags: [API Keys]
      x-internal: true
      summary: Create API key group
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Group created

  /api/keys/groups/{id}:
    get:
      tags: [API Keys]
      x-internal: true
      summary: Get API key group
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group details
    patch:
      tags: [API Keys]
      x-internal: true
      summary: Update API key group
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Group updated
    delete:
      tags: [API Keys]
      x-internal: true
      summary: Delete API key group
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Group deleted

  /api/keys/groups/{id}/keys:
    get:
      tags: [API Keys]
      x-internal: true
      summary: List keys in group
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Keys in group
    post:
      tags: [API Keys]
      x-internal: true
      summary: Add key to group
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Key added

  /api/keys/groups/{id}/permissions:
    get:
      tags: [API Keys]
      x-internal: true
      summary: Get group permissions
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Permissions
    patch:
      tags: [API Keys]
      x-internal: true
      summary: Update group permissions
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Permissions updated

  /api/keys/{id}/regenerate:
    post:
      tags: [API Keys]
      x-internal: true
      summary: Regenerate API key secret
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: New key value

  /api/keys/{id}/reveal:
    post:
      tags: [API Keys]
      x-internal: true
      summary: Reveal API key value
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Key value (one-time reveal)

  /api/resilience/model-cooldowns:
    get:
      tags: [System]
      x-internal: true
      summary: List model cooldown state
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Model cooldown entries

  /api/a2a/status:
    get:
      tags: [A2A]
      x-internal: true
      summary: A2A server status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: A2A status

  /api/a2a/tasks:
    get:
      tags: [A2A]
      x-internal: true
      summary: List A2A tasks
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: A2A task list
    post:
      tags: [A2A]
      x-internal: true
      summary: Create A2A task
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Task created

  /api/a2a/tasks/{id}:
    get:
      tags: [A2A]
      x-internal: true
      summary: Get A2A task
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task details

  /api/a2a/tasks/{id}/cancel:
    post:
      tags: [A2A]
      x-internal: true
      summary: Cancel A2A task
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Task cancelled

  /api/acp/agents:
    get:
      tags: [A2A]
      x-internal: true
      summary: List ACP agents
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Agent list

  /api/db/health:
    get:
      tags: [System]
      x-internal: true
      summary: Database health check
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: DB health

  /api/evals/suites:
    get:
      tags: [Evals]
      x-internal: true
      summary: List eval suites
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Suite list
    post:
      tags: [Evals]
      x-internal: true
      summary: Create eval suite
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Suite created

  /api/evals/suites/{suiteId}:
    get:
      tags: [Evals]
      x-internal: true
      summary: Get eval suite details
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: suiteId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Suite details
    patch:
      tags: [Evals]
      x-internal: true
      summary: Update eval suite
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: suiteId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Suite updated

  /api/files:
    get:
      tags: [Files]
      x-internal: true
      summary: List files (management view)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: File list
    post:
      tags: [Files]
      x-internal: true
      summary: Upload file (management)
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "201":
          description: File uploaded

  /api/files/{id}/content:
    get:
      tags: [Files]
      x-internal: true
      summary: Get file content (management)
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content

  /api/batches:
    get:
      tags: [Batches]
      x-internal: true
      summary: List batch jobs (management)
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Batch list
    post:
      tags: [Batches]
      x-internal: true
      summary: Create batch job (management)
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Batch created

  /api/batches/{id}:
    get:
      tags: [Batches]
      x-internal: true
      summary: Get batch job (management)
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch details
    delete:
      tags: [Batches]
      x-internal: true
      summary: Delete batch job (management)
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Batch deleted

  /api/internal/codex-responses-ws:
    get:
      tags: [System]
      x-internal: true
      summary: Codex responses WebSocket (internal)
      security:
        - BearerAuth: []
      responses:
        "101":
          description: WebSocket upgrade

  /api/openapi/try:
    post:
      tags: [System]
      x-internal: true
      summary: Try It — execute an API request via proxy
      description: Internal endpoint used by the API Explorer "Try It" feature.
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                method:
                  type: string
                path:
                  type: string
                body:
                  type: object
      responses:
        "200":
          description: Try result

  /api/pricing/sync:
    post:
      tags: [Pricing]
      x-internal: true
      summary: Sync pricing data
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Pricing synced

  /api/auth/status:
    get:
      tags: [System]
      x-internal: true
      summary: Auth session status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Auth status

  /api/model-combo-mappings:
    get:
      tags: [Combos]
      x-internal: true
      summary: List model combo mappings
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Mappings
    post:
      tags: [Combos]
      x-internal: true
      summary: Create model combo mapping
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "201":
          description: Mapping created

  /api/model-combo-mappings/{id}:
    patch:
      tags: [Combos]
      x-internal: true
      summary: Update model combo mapping
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Mapping updated
    delete:
      tags: [Combos]
      x-internal: true
      summary: Delete model combo mapping
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Mapping deleted

  /api/combos/builder/options:
    get:
      tags: [Combos]
      x-internal: true
      summary: Combo builder options
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: Builder options

  /api/combos/reorder:
    patch:
      tags: [Combos]
      x-internal: true
      summary: Reorder combos
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Reordered

  /api/providers/claude-auth/import:
    post:
      tags: [Providers]
      x-internal: true
      summary: Import Claude auth session
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/providers/claude-auth/import-bulk:
    post:
      tags: [Providers]
      x-internal: true
      summary: Bulk import Claude auth sessions
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk import result

  /api/providers/claude-auth/zip-extract:
    post:
      tags: [Providers]
      x-internal: true
      summary: Extract Claude auth ZIP
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "200":
          description: Extract result

  /api/providers/codex-auth/import:
    post:
      tags: [Providers]
      x-internal: true
      summary: Import Codex auth session
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/providers/codex-auth/import-bulk:
    post:
      tags: [Providers]
      x-internal: true
      summary: Bulk import Codex auth sessions
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk import result

  /api/providers/codex-auth/zip-extract:
    post:
      tags: [Providers]
      x-internal: true
      summary: Extract Codex auth ZIP
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "200":
          description: Extract result

  /api/providers/command-code/auth/start:
    post:
      tags: [Providers]
      x-internal: true
      summary: Start Command Code OAuth flow
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: OAuth flow started

  /api/providers/command-code/auth/callback:
    get:
      tags: [Providers]
      x-internal: true
      summary: Command Code OAuth callback
      responses:
        "302":
          description: OAuth redirect

  /api/providers/command-code/auth/apply:
    post:
      tags: [Providers]
      x-internal: true
      summary: Apply Command Code OAuth token
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Token applied

  /api/providers/command-code/auth/status:
    get:
      tags: [Providers]
      x-internal: true
      summary: Command Code OAuth status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: OAuth status

  /api/providers/gemini-cli-auth/import:
    post:
      tags: [Providers]
      x-internal: true
      summary: Import Gemini CLI auth session
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/providers/gemini-cli-auth/import-bulk:
    post:
      tags: [Providers]
      x-internal: true
      summary: Bulk import Gemini CLI auth sessions
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Bulk import result

  /api/providers/gemini-cli-auth/zip-extract:
    post:
      tags: [Providers]
      x-internal: true
      summary: Extract Gemini CLI auth ZIP
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
      responses:
        "200":
          description: Extract result

  /api/providers/{id}/claude-auth/apply-local:
    post:
      tags: [Providers]
      x-internal: true
      summary: Apply local Claude auth to provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Auth applied

  /api/providers/{id}/claude-auth/export:
    post:
      tags: [Providers]
      x-internal: true
      summary: Export Claude auth from provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Auth exported

  /api/providers/{id}/codex-auth/apply-local:
    post:
      tags: [Providers]
      x-internal: true
      summary: Apply local Codex auth to provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Auth applied

  /api/providers/{id}/codex-auth/export:
    post:
      tags: [Providers]
      x-internal: true
      summary: Export Codex auth from provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Auth exported

  /api/providers/{id}/gemini-cli-auth/apply-local:
    post:
      tags: [Providers]
      x-internal: true
      summary: Apply local Gemini CLI auth to provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Auth applied

  /api/providers/{id}/gemini-cli-auth/export:
    post:
      tags: [Providers]
      x-internal: true
      summary: Export Gemini CLI auth from provider
      security:
        - ManagementSessionAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Auth exported

  /api/providers/zed/import:
    post:
      tags: [Providers]
      x-internal: true
      summary: Import Zed auth session
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/providers/zed/manual-import:
    post:
      tags: [Providers]
      x-internal: true
      summary: Manual Zed auth import
      security:
        - ManagementSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Import result

  /api/skills/skillssh:
    get:
      tags: [Skills]
      x-internal: true
      summary: SkillSSH status
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: SkillSSH status

  /api/skills/skillssh/install:
    post:
      tags: [Skills]
      x-internal: true
      summary: Install SkillSSH
      security:
        - ManagementSessionAuth: []
      responses:
        "200":
          description: SkillSSH installed

  /api/translator/transform-stream:
    post:
      tags: [Translator]
      x-internal: true
      summary: Transform stream (internal)
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        "200":
          description: Transform result

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:
    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