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

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

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

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

tags:
  - name: Chat
    description: OpenAI-compatible chat completions
  - name: Messages
    description: Anthropic-compatible messages
  - name: Responses
    description: OpenAI Responses API
  - name: Embeddings
    description: Text embedding generation
  - name: Images
    description: Image generation
  - name: Audio
    description: Audio speech and transcription
  - name: Moderations
    description: Content moderation
  - name: Rerank
    description: Document reranking
  - name: Models
    description: Available model listing
  - name: Providers
    description: Provider connection management
  - name: Provider Nodes
    description: Provider node configuration
  - name: API Keys
    description: API key management
  - name: Combos
    description: Routing combo management
  - name: Settings
    description: Application settings
  - name: 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  /api/translator/load:
    get:
      tags: [Translator]
      summary: Load saved translation template
      responses:
        "200":
          description: Template data

  /api/translator/save:
    post:
      tags: [Translator]
      summary: Save translation template
      responses:
        "200":
          description: Template saved

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  /api/compliance/audit-log:
    get:
      tags: [System]
      summary: Get compliance audit log
      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

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, content]
            properties:
              role:
                type: string
                enum: [system, user, assistant]
              content:
                type: string
        stream:
          type: boolean
          default: false
        temperature:
          type: number
          minimum: 0
          maximum: 2
        max_tokens:
          type: integer

    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, random, least-used, cost-optimized]
          default: priority
        nodes:
          type: array
          items:
            type: object
            properties:
              connectionId:
                type: string
              weight:
                type: integer
              priority:
                type: integer