Files
OmniRoute/docs/reference/openapi.yaml

4265 lines
112 KiB
YAML

openapi: 3.1.0
info:
title: OmniRoute API
version: 3.8.6
description: |
OmniRoute is a local-first AI API proxy router. It provides an OpenAI-compatible
endpoint that routes requests to multiple AI providers with load balancing,
failover, and usage tracking.
## Base URLs
- **Local**: `http://localhost:20128`
## Authentication
All proxy endpoints require a Bearer token (API key managed via the dashboard).
Management endpoints are protected when `requireLogin` is enabled.
contact:
name: OmniRoute
license:
name: MIT
servers:
- url: http://localhost:20128
description: Local development
tags:
- name: Chat
description: OpenAI-compatible chat completions
- name: Messages
description: Anthropic-compatible messages
- name: Responses
description: OpenAI Responses API
- name: Embeddings
description: Text embedding generation
- name: Images
description: Image generation
- name: Audio
description: Audio speech and transcription
- name: Moderations
description: Content moderation
- name: Rerank
description: Document reranking
- name: Models
description: Available model listing
- name: Providers
description: Provider connection management
- name: Provider Nodes
description: Provider node configuration
- name: API Keys
description: API key management
- name: Combos
description: Routing combo management
- name: Settings
description: Application settings
- name: Compression
description: Prompt compression, RTK filters, Caveman rules, and compression combos
- name: Usage
description: Usage analytics and logs
- name: Translator
description: Format translation debug & testing
- name: CLI Tools
description: CLI tool configuration management
- name: Embedded Services
description: >-
Install, start, stop, and monitor locally-running embedded services (9Router, CLIProxyAPI).
All routes are LOCAL_ONLY — accessible from loopback only (hard rule #17).
- name: OAuth
description: OAuth flows for provider authentication
- name: System
description: System management (restart, shutdown, backup)
- name: Pricing
description: Model pricing configuration
- name: Cloud
description: Cloud worker authentication and sync
- name: Fallback
description: Fallback chain management
- name: Telemetry
description: Telemetry and token health monitoring
- name: AgentBridge
description: >-
MITM proxy manager for 9 IDE agents (Antigravity, Kiro, Copilot, Codex, Cursor, Zed,
Claude Code, Open Code, Trae). Controls server lifecycle, DNS/model mappings, bypass list,
and cert management. All routes are LOCAL_ONLY + SPAWN_CAPABLE (hard rules #15, #17).
See docs/frameworks/AGENTBRIDGE.md.
- name: Traffic Inspector
description: >-
LLM-aware HTTPS traffic debugger with 4 capture modes (AgentBridge, Custom Hosts,
HTTP_PROXY :8080, System-wide). Provides real-time WebSocket stream, session recording,
HAR export, SSE merge, and conversation normalization.
All routes are LOCAL_ONLY + SPAWN_CAPABLE (hard rules #15, #17).
See docs/frameworks/TRAFFIC_INSPECTOR.md.
paths:
# ─── Proxy Endpoints ──────────────────────────────────────────
/api/v1/chat/completions:
post:
tags: [Chat]
summary: Create chat completion
description: OpenAI-compatible chat completions endpoint. Routes to configured providers.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatCompletionRequest"
responses:
"200":
description: Chat completion response (or SSE stream)
content:
application/json:
schema:
$ref: "#/components/schemas/ChatCompletionResponse"
text/event-stream:
schema:
type: string
"401":
$ref: "#/components/responses/Unauthorized"
"502":
description: All upstream providers failed
/api/v1/providers/{provider}/chat/completions:
post:
tags: [Chat]
summary: Create chat completion (provider-specific)
description: Routes to a specific provider by name.
security:
- BearerAuth: []
parameters:
- name: provider
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatCompletionRequest"
responses:
"200":
description: Chat completion response
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/api/chat:
post:
tags: [Chat]
summary: Ollama-compatible chat endpoint
description: Provides compatibility with Ollama's /api/chat format.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Chat response (JSON or streaming)
/api/v1/messages:
post:
tags: [Messages]
summary: Create message (Anthropic-compatible)
description: Anthropic Messages API endpoint. Routes to Claude providers.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MessagesRequest"
responses:
"200":
description: Message response (or SSE stream)
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/messages/count_tokens:
post:
tags: [Messages]
summary: Count tokens for a message
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Token count
/api/v1/responses:
post:
tags: [Responses]
summary: Create response (OpenAI Responses API)
description: OpenAI Responses API endpoint.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Response object or SSE stream
"401":
$ref: "#/components/responses/Unauthorized"
/api/v1/embeddings:
post:
tags: [Embeddings]
summary: Create embeddings
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [input, model]
properties:
input:
oneOf:
- type: string
- type: array
items:
type: string
model:
type: string
responses:
"200":
description: Embedding vectors
/api/v1/providers/{provider}/embeddings:
post:
tags: [Embeddings]
summary: Create embeddings (provider-specific)
security:
- BearerAuth: []
parameters:
- name: provider
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Embedding vectors
/api/v1/images/generations:
post:
tags: [Images]
summary: Generate images
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [prompt]
properties:
prompt:
type: string
model:
type: string
n:
type: integer
default: 1
size:
type: string
default: 1024x1024
responses:
"200":
description: Generated images
/api/v1/providers/{provider}/images/generations:
post:
tags: [Images]
summary: Generate images (provider-specific)
security:
- BearerAuth: []
parameters:
- name: provider
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Generated images
/api/v1/audio/speech:
post:
tags: [Audio]
summary: Generate speech audio
description: Text-to-speech endpoint. Routes to configured TTS providers.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [input]
properties:
input:
type: string
model:
type: string
voice:
type: string
responses:
"200":
description: Audio data
/api/v1/audio/transcriptions:
post:
tags: [Audio]
summary: Transcribe audio
description: Audio-to-text transcription endpoint.
security:
- BearerAuth: []
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required: [file]
properties:
file:
type: string
format: binary
model:
type: string
responses:
"200":
description: Transcription result
/api/v1/moderations:
post:
tags: [Moderations]
summary: Create moderation
description: Content moderation endpoint. Routes to configured moderation providers.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [input]
properties:
input:
oneOf:
- type: string
- type: array
items:
type: string
responses:
"200":
description: Moderation result
/api/v1/rerank:
post:
tags: [Rerank]
summary: Rerank documents
description: Document reranking endpoint.
security:
- BearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [query, documents]
properties:
query:
type: string
documents:
type: array
items:
type: string
model:
type: string
responses:
"200":
description: Reranked documents
/api/v1:
get:
tags: [System]
summary: API v1 root endpoint
description: Returns basic API info and status.
security:
- BearerAuth: []
responses:
"200":
description: API info
/api/v1/models:
get:
tags: [Models]
summary: List available models
description: Returns all models available across configured providers.
security:
- BearerAuth: []
responses:
"200":
description: Model list
content:
application/json:
schema:
type: object
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: "#/components/schemas/Model"
/api/v1/providers/{provider}/models:
get:
tags: [Models]
summary: List models for a specific provider
description: Returns only models for the selected provider with provider prefix removed from each model id.
security:
- BearerAuth: []
parameters:
- in: path
name: provider
required: true
schema:
type: string
description: Provider id or alias (for example `openai`, `claude`, `cc`).
responses:
"200":
description: Provider-scoped model list
content:
application/json:
schema:
type: object
properties:
object:
type: string
example: list
data:
type: array
items:
$ref: "#/components/schemas/Model"
"400":
description: Unknown provider
/api/models:
get:
tags: [Models]
summary: List models (management)
responses:
"200":
description: Internal model list with aliases
/api/models/alias:
post:
tags: [Models]
summary: Create or update a model alias
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Alias created/updated
/api/models/catalog:
get:
tags: [Models]
summary: Get full model catalog
responses:
"200":
description: Complete catalog with all providers
# ─── Management Endpoints ──────────────────────────────────────
/api/providers:
get:
tags: [Providers]
summary: List provider connections
responses:
"200":
description: Provider connection list
content:
application/json:
schema:
type: object
properties:
connections:
type: array
items:
$ref: "#/components/schemas/ProviderConnection"
post:
tags: [Providers]
summary: Create provider connection
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ProviderConnectionCreate"
responses:
"201":
description: Created provider connection
/api/providers/{id}:
get:
tags: [Providers]
summary: Get provider connection
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Provider connection details
"404":
description: Provider not found
patch:
tags: [Providers]
summary: Update provider connection
parameters:
- $ref: "#/components/parameters/ResourceId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ProviderConnectionCreate"
responses:
"200":
description: Updated provider
delete:
tags: [Providers]
summary: Delete provider connection
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Provider deleted
/api/providers/{id}/test:
post:
tags: [Providers]
summary: Test provider connection
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Test result
/api/providers/{id}/models:
get:
tags: [Providers]
summary: List models for a provider
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Provider model list
/api/providers/test-batch:
post:
tags: [Providers]
summary: Test multiple providers at once
responses:
"200":
description: Batch test results
/api/providers/validate:
post:
tags: [Providers]
summary: Validate provider credentials
responses:
"200":
description: Validation result
/api/providers/client:
get:
tags: [Providers]
summary: Get client-side provider info
responses:
"200":
description: Provider info for frontend
/api/provider-nodes:
get:
tags: [Provider Nodes]
summary: List provider nodes
responses:
"200":
description: Provider node list
post:
tags: [Provider Nodes]
summary: Create provider node
responses:
"201":
description: Created node
/api/provider-nodes/{id}:
patch:
tags: [Provider Nodes]
summary: Update provider node
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Updated node
delete:
tags: [Provider Nodes]
summary: Delete provider node
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Node deleted
/api/provider-nodes/validate:
post:
tags: [Provider Nodes]
summary: Validate a provider node
responses:
"200":
description: Validation result
/api/provider-models:
get:
tags: [Provider Nodes]
summary: List provider models
responses:
"200":
description: Provider model list
/api/keys:
get:
tags: [API Keys]
summary: List API keys
responses:
"200":
description: API key list
content:
application/json:
schema:
type: object
properties:
keys:
type: array
items:
$ref: "#/components/schemas/ApiKey"
post:
tags: [API Keys]
summary: Create API key
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [label]
properties:
label:
type: string
responses:
"201":
description: Created API key (includes full key value)
/api/keys/{id}:
delete:
tags: [API Keys]
summary: Delete API key
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Key deleted
/api/combos:
get:
tags: [Combos]
summary: List routing combos
responses:
"200":
description: Combo list
post:
tags: [Combos]
summary: Create routing combo
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ComboCreate"
responses:
"201":
description: Created combo
/api/combos/{id}:
patch:
tags: [Combos]
summary: Update combo
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Updated combo
delete:
tags: [Combos]
summary: Delete combo
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Combo deleted
/api/combos/metrics:
get:
tags: [Combos]
summary: Get combo metrics
responses:
"200":
description: Metrics for combos
/api/combos/test:
post:
tags: [Combos]
summary: Test a combo configuration
responses:
"200":
description: Test result
/api/settings:
get:
tags: [Settings]
summary: Get application settings
responses:
"200":
description: Current settings
patch:
tags: [Settings]
summary: Update settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated settings
/api/settings/compression:
get:
tags: [Compression]
summary: Get global compression settings
security:
- ManagementSessionAuth: []
responses:
"200":
description: Current compression settings
put:
tags: [Compression]
summary: Update global compression settings
security:
- ManagementSessionAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
defaultMode:
type: string
enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
autoTriggerMode:
type: string
enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
autoTriggerTokens:
type: integer
minimum: 0
rtkConfig:
type: object
additionalProperties: true
stackedPipeline:
type: array
items:
type: object
responses:
"200":
description: Updated compression settings
/api/compression/preview:
post:
tags: [Compression]
summary: Preview compression for a message payload
security:
- BearerAuth: []
- ManagementSessionAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [messages, mode]
properties:
mode:
type: string
enum: [off, lite, standard, aggressive, ultra, rtk, stacked]
messages:
type: array
items:
type: object
required: [role, content]
properties:
role:
type: string
content:
oneOf:
- type: string
- type: array
items: {}
config:
type: object
additionalProperties: true
responses:
"200":
description: Compression preview with diff, validation, and stats
/api/compression/language-packs:
get:
tags: [Compression]
summary: List Caveman compression language packs
security:
- BearerAuth: []
- ManagementSessionAuth: []
responses:
"200":
description: Available languages and rule-pack metadata
/api/compression/rules:
get:
tags: [Compression]
summary: List Caveman compression rule metadata
security:
- BearerAuth: []
- ManagementSessionAuth: []
responses:
"200":
description: Caveman rule metadata
/api/context/rtk/config:
get:
tags: [Compression]
summary: Get RTK compression settings
security:
- ManagementSessionAuth: []
responses:
"200":
description: Current RTK config
put:
tags: [Compression]
summary: Update RTK compression settings
security:
- ManagementSessionAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
intensity:
type: string
enum: [minimal, standard, aggressive]
customFiltersEnabled:
type: boolean
trustProjectFilters:
type: boolean
rawOutputRetention:
type: string
enum: [never, failures, always]
rawOutputMaxBytes:
type: integer
responses:
"200":
description: Updated RTK config
/api/context/rtk/filters:
get:
tags: [Compression]
summary: List RTK filters and load diagnostics
security:
- ManagementSessionAuth: []
responses:
"200":
description: RTK filter catalog and diagnostics
/api/context/rtk/test:
post:
tags: [Compression]
summary: Run RTK compression preview for text
security:
- ManagementSessionAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [text]
properties:
text:
type: string
command:
type: string
config:
type: object
additionalProperties: true
responses:
"200":
description: Detection and RTK compression result
/api/context/rtk/raw-output/{id}:
get:
tags: [Compression]
summary: Read retained redacted RTK raw output
security:
- ManagementSessionAuth: []
parameters:
- in: path
name: id
required: true
schema:
type: string
pattern: "^[a-f0-9]{24}$"
responses:
"200":
description: Raw output text
"404":
description: Raw output not found
/api/settings/payload-rules:
get:
tags: [Settings]
summary: Get payload rules configuration
description: |
Returns the current payload rules used to mutate outgoing request payloads before they
are sent upstream.
Requires a dashboard management session cookie when management auth is enabled.
security:
- ManagementSessionAuth: []
responses:
"200":
description: Current payload rules configuration
content:
application/json:
schema:
$ref: "#/components/schemas/PayloadRulesConfig"
"401":
$ref: "#/components/responses/ManagementAuthenticationRequired"
"403":
$ref: "#/components/responses/ManagementInvalidToken"
"500":
description: Failed to read payload rules configuration
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
put:
tags: [Settings]
summary: Update payload rules configuration
description: |
Persists and hot reloads payload rules. The legacy input field `default-raw` is accepted
on writes and normalized to `defaultRaw` in responses/runtime state.
Requires a dashboard management session cookie when management auth is enabled.
security:
- ManagementSessionAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdatePayloadRulesRequest"
responses:
"200":
description: Updated payload rules configuration
content:
application/json:
schema:
$ref: "#/components/schemas/PayloadRulesConfig"
"400":
$ref: "#/components/responses/ValidationError"
"401":
$ref: "#/components/responses/ManagementAuthenticationRequired"
"403":
$ref: "#/components/responses/ManagementInvalidToken"
"500":
description: Failed to update payload rules configuration
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
/api/settings/combo-defaults:
get:
tags: [Settings]
summary: Get combo default settings
responses:
"200":
description: Default combo settings
/api/settings/proxy:
get:
tags: [Settings]
summary: Get proxy settings
responses:
"200":
description: Current proxy settings
patch:
tags: [Settings]
summary: Update proxy settings
responses:
"200":
description: Updated proxy settings
/api/settings/proxy/test:
post:
tags: [Settings]
summary: Test proxy connection
responses:
"200":
description: Test result
/api/settings/require-login:
post:
tags: [Settings]
summary: Toggle login requirement
responses:
"200":
description: Updated
/api/settings/ip-filter:
get:
tags: [Settings]
summary: Get IP filter configuration
description: Returns the current IP filter settings including blacklist, whitelist, and temp bans.
responses:
"200":
description: IP filter configuration
put:
tags: [Settings]
summary: Update IP filter configuration
description: |
Configure IP filtering with blacklist/whitelist modes, add/remove individual IPs, and manage temp bans.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
enabled:
type: boolean
mode:
type: string
enum: [blacklist, whitelist]
blacklist:
type: array
items:
type: string
whitelist:
type: array
items:
type: string
addBlacklist:
type: string
removeBlacklist:
type: string
addWhitelist:
type: string
removeWhitelist:
type: string
tempBan:
type: object
properties:
ip:
type: string
durationMs:
type: integer
reason:
type: string
removeBan:
type: string
responses:
"200":
description: Updated IP filter configuration
/api/settings/system-prompt:
get:
tags: [Settings]
summary: Get system prompt configuration
description: Returns the current system prompt injection settings.
responses:
"200":
description: System prompt configuration
put:
tags: [Settings]
summary: Update system prompt configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
prompt:
type: string
enabled:
type: boolean
responses:
"200":
description: Updated system prompt configuration
/api/settings/thinking-budget:
get:
tags: [Settings]
summary: Get thinking budget configuration
description: Returns the current thinking/reasoning budget settings for AI models.
responses:
"200":
description: Thinking budget configuration
put:
tags: [Settings]
summary: Update thinking budget configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
mode:
type: string
description: Thinking mode (e.g., auto, manual, disabled)
customBudget:
type: integer
minimum: 0
maximum: 131072
effortLevel:
type: string
enum: [none, low, medium, high]
responses:
"200":
description: Updated thinking budget configuration
/api/rate-limit:
get:
tags: [Settings]
summary: Get rate limit configuration
responses:
"200":
description: Rate limit settings
post:
tags: [Settings]
summary: Update rate limit configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated rate limit settings
/api/tags:
get:
tags: [System]
summary: List Ollama-compatible model tags
description: Returns models in Ollama /api/tags format for Ollama client compatibility
responses:
"200":
description: Ollama model tags
# ─── Usage & Analytics ─────────────────────────────────────────
/api/usage/analytics:
get:
tags: [Usage]
summary: Get usage analytics
parameters:
- name: period
in: query
schema:
type: string
enum: [day, week, month]
default: day
responses:
"200":
description: Usage analytics data
/api/usage/call-logs:
get:
tags: [Usage]
summary: Get call logs
parameters:
- name: limit
in: query
schema:
type: integer
default: 50
- name: offset
in: query
schema:
type: integer
default: 0
responses:
"200":
description: Paginated call logs
/api/usage/call-logs/{id}:
get:
tags: [Usage]
summary: Get a specific call log
parameters:
- $ref: "#/components/parameters/ResourceId"
responses:
"200":
description: Call log detail
/api/usage/{connectionId}:
get:
tags: [Usage]
summary: Get usage for a specific connection
parameters:
- name: connectionId
in: path
required: true
schema:
type: string
responses:
"200":
description: Connection usage data
/api/usage/history:
get:
tags: [Usage]
summary: Get usage history
responses:
"200":
description: Historical usage data
/api/usage/logs:
get:
tags: [Usage]
summary: Get usage logs
responses:
"200":
description: Usage log entries
/api/usage/proxy-logs:
get:
tags: [Usage]
summary: Get proxy logs
responses:
"200":
description: Proxy log entries
/api/usage/request-logs:
get:
tags: [Usage]
summary: Get request logs
responses:
"200":
description: Request log entries
/api/usage/budget:
get:
tags: [Usage]
summary: Get usage budget status
description: Returns current budget limits and consumption.
responses:
"200":
description: Budget status
post:
tags: [Usage]
summary: Configure usage budget
description: Set or update budget limits for usage tracking.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated budget configuration
# ─── Pricing ───────────────────────────────────────────────────
/api/pricing:
get:
tags: [Pricing]
summary: Get model pricing
responses:
"200":
description: Current pricing configuration
post:
tags: [Pricing]
summary: Set model pricing
responses:
"200":
description: Updated pricing
/api/pricing/defaults:
get:
tags: [Pricing]
summary: Get default pricing
responses:
"200":
description: Default pricing data
/api/pricing/models:
get:
tags: [Pricing]
summary: Get pricing per model
description: Returns pricing information organized by model.
responses:
"200":
description: Per-model pricing data
# ─── Translator ────────────────────────────────────────────────
/api/translator/detect:
post:
tags: [Translator]
summary: Detect request format
description: Detects the API format of a request body (OpenAI, Claude, Gemini, etc.)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [body]
properties:
body:
type: object
responses:
"200":
description: Detected format
/api/translator/translate:
post:
tags: [Translator]
summary: Translate between formats
description: Converts a request between API formats (e.g. Claude → OpenAI)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [sourceFormat, targetFormat, body]
properties:
step:
type: string
sourceFormat:
type: string
targetFormat:
type: string
provider:
type: string
body:
type: object
responses:
"200":
description: Translated request
/api/translator/send:
post:
tags: [Translator]
summary: Send translated request to provider
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [provider, body]
properties:
provider:
type: string
body:
type: object
responses:
"200":
description: Provider response (may be SSE stream)
/api/translator/history:
get:
tags: [Translator]
summary: Get translation history
description: Returns recent translation events for the Live Monitor
responses:
"200":
description: Translation history entries
# ─── CLI Tools ─────────────────────────────────────────────────
/api/cli-tools/backups:
get:
tags: [CLI Tools]
summary: List CLI tool backups
responses:
"200":
description: Backup list
post:
tags: [CLI Tools]
summary: Create CLI tool backup
responses:
"200":
description: Backup created
/api/cli-tools/runtime/{toolId}:
get:
tags: [CLI Tools]
summary: Get runtime status for a CLI tool
parameters:
- name: toolId
in: path
required: true
schema:
type: string
responses:
"200":
description: Runtime status
/api/cli-tools/guide-settings/{toolId}:
get:
tags: [CLI Tools]
summary: Get guide settings for a tool
parameters:
- name: toolId
in: path
required: true
schema:
type: string
responses:
"200":
description: Guide settings
/api/cli-tools/antigravity-mitm:
get:
tags: [CLI Tools]
summary: Get Antigravity MITM proxy settings
responses:
"200":
description: MITM proxy configuration
post:
tags: [CLI Tools]
summary: Update Antigravity MITM proxy settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated MITM proxy configuration
delete:
tags: [CLI Tools]
summary: Reset Antigravity MITM proxy settings
responses:
"200":
description: MITM proxy settings reset
/api/cli-tools/antigravity-mitm/alias:
get:
tags: [CLI Tools]
summary: Get Antigravity MITM alias configuration
responses:
"200":
description: Alias configuration
put:
tags: [CLI Tools]
summary: Update Antigravity MITM alias configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated alias configuration
/api/cli-tools/claude-settings:
get:
tags: [CLI Tools]
summary: Get Claude CLI settings
responses:
"200":
description: Claude CLI configuration
post:
tags: [CLI Tools]
summary: Apply Claude CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Claude CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset Claude CLI settings
responses:
"200":
description: Claude CLI settings reset
/api/cli-tools/cline-settings:
get:
tags: [CLI Tools]
summary: Get Cline CLI settings
responses:
"200":
description: Cline CLI configuration
post:
tags: [CLI Tools]
summary: Apply Cline CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Cline CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset Cline CLI settings
responses:
"200":
description: Cline CLI settings reset
/api/cli-tools/codex-profiles:
get:
tags: [CLI Tools]
summary: Get Codex profiles
responses:
"200":
description: Codex profile list
post:
tags: [CLI Tools]
summary: Create Codex profile
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Profile created
put:
tags: [CLI Tools]
summary: Update Codex profile
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Profile updated
delete:
tags: [CLI Tools]
summary: Delete Codex profile
responses:
"200":
description: Profile deleted
/api/cli-tools/codex-settings:
get:
tags: [CLI Tools]
summary: Get Codex CLI settings
responses:
"200":
description: Codex CLI configuration
post:
tags: [CLI Tools]
summary: Apply Codex CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Codex CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset Codex CLI settings
responses:
"200":
description: Codex CLI settings reset
/api/cli-tools/droid-settings:
get:
tags: [CLI Tools]
summary: Get Droid CLI settings
responses:
"200":
description: Droid CLI configuration
post:
tags: [CLI Tools]
summary: Apply Droid CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Droid CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset Droid CLI settings
responses:
"200":
description: Droid CLI settings reset
/api/cli-tools/kilo-settings:
get:
tags: [CLI Tools]
summary: Get Kilo CLI settings
responses:
"200":
description: Kilo CLI configuration
post:
tags: [CLI Tools]
summary: Apply Kilo CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Kilo CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset Kilo CLI settings
responses:
"200":
description: Kilo CLI settings reset
/api/cli-tools/openclaw-settings:
get:
tags: [CLI Tools]
summary: Get OpenClaw CLI settings
responses:
"200":
description: OpenClaw CLI configuration
post:
tags: [CLI Tools]
summary: Apply OpenClaw CLI settings
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: OpenClaw CLI settings applied
delete:
tags: [CLI Tools]
summary: Reset OpenClaw CLI settings
responses:
"200":
description: OpenClaw CLI settings reset
# ─── Embedded Services ─────────────────────────────────────────
# All routes LOCAL_ONLY (loopback only) — hard rule #17.
# See docs/frameworks/EMBEDDED-SERVICES.md for full reference.
/api/services/9router/install:
post:
tags: [Embedded Services]
summary: Install 9Router from npm
description: >-
Installs the `9router` npm package under DATA_DIR/services/9router/.
Uses execFile (no shell interpolation — hard rule #13).
**LOCAL_ONLY** — loopback only.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
version:
type: string
default: latest
description: npm version tag or semver to install
responses:
"200":
description: Install succeeded
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
installedVersion:
type: string
path:
type: string
"400":
description: Invalid request body
"500":
description: npm install failed
/api/services/9router/start:
post:
tags: [Embedded Services]
summary: Start 9Router
description: >-
Spawns the 9Router process. Idempotent if already running.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service started (or already running)
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
"409":
description: 9Router is not installed
"503":
description: Start failed
/api/services/9router/stop:
post:
tags: [Embedded Services]
summary: Stop 9Router
description: >-
Gracefully stops 9Router (SIGTERM → 15 s → SIGKILL). Idempotent.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service stopped
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
"503":
description: Stop failed
/api/services/9router/restart:
post:
tags: [Embedded Services]
summary: Restart 9Router
description: >-
Equivalent to stop() then start() under the operation lock.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service restarted
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
/api/services/9router/update:
post:
tags: [Embedded Services]
summary: Update 9Router to a newer npm version
description: >-
Stops the service (if running), installs the newer npm version, then restarts.
**LOCAL_ONLY** — loopback only.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
version:
type: string
default: latest
responses:
"200":
description: Update succeeded
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
previousVersion:
type: string
installedVersion:
type: string
"400":
description: Invalid request body
"500":
description: Update failed
/api/services/9router/rotate-key:
post:
tags: [Embedded Services]
summary: Rotate the 9Router API key
description: >-
Generates a new API key, encrypts it at-rest, and restarts the service to
apply it. The plaintext key is never returned.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Key rotated
content:
application/json:
schema:
type: object
properties:
keyRotated:
type: boolean
restarted:
type: boolean
"500":
description: Rotation failed
/api/services/9router/status:
get:
tags: [Embedded Services]
summary: Get 9Router status
description: >-
Returns combined live supervisor state and DB metadata.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Status response
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatusExtended"
"500":
description: Status read failed
/api/services/9router/auto-start:
post:
tags: [Embedded Services]
summary: Toggle 9Router auto-start
description: >-
When enabled, 9Router starts automatically on the next OmniRoute boot.
**LOCAL_ONLY** — loopback only.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled]
properties:
enabled:
type: boolean
responses:
"200":
description: Auto-start flag updated
content:
application/json:
schema:
type: object
properties:
autoStart:
type: boolean
"400":
description: Invalid request body
/api/services/cliproxy/install:
post:
tags: [Embedded Services]
summary: Install CLIProxyAPI from npm
description: >-
Installs the CLIProxyAPI package under DATA_DIR/services/cliproxy/.
**LOCAL_ONLY** — loopback only.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
version:
type: string
default: latest
responses:
"200":
description: Install succeeded
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
installedVersion:
type: string
"400":
description: Invalid request body
"500":
description: npm install failed
/api/services/cliproxy/start:
post:
tags: [Embedded Services]
summary: Start CLIProxyAPI
description: >-
Spawns the CLIProxyAPI process. Idempotent if already running.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service started
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
"409":
description: CLIProxyAPI is not installed
"503":
description: Start failed
/api/services/cliproxy/stop:
post:
tags: [Embedded Services]
summary: Stop CLIProxyAPI
description: >-
Gracefully stops CLIProxyAPI. Idempotent.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service stopped
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
/api/services/cliproxy/restart:
post:
tags: [Embedded Services]
summary: Restart CLIProxyAPI
description: >-
stop() then start() under the operation lock.
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Service restarted
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
/api/services/cliproxy/update:
post:
tags: [Embedded Services]
summary: Update CLIProxyAPI to a newer npm version
description: >-
Stops, installs newer version, restarts.
**LOCAL_ONLY** — loopback only.
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
version:
type: string
default: latest
responses:
"200":
description: Update succeeded
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
installedVersion:
type: string
"500":
description: Update failed
/api/services/cliproxy/status:
get:
tags: [Embedded Services]
summary: Get CLIProxyAPI status
description: >-
Returns live supervisor state and DB metadata (no apiKeyMasked — CLIProxyAPI
does not use an injected API key).
**LOCAL_ONLY** — loopback only.
responses:
"200":
description: Status response
content:
application/json:
schema:
$ref: "#/components/schemas/ServiceStatus"
/api/services/cliproxy/auto-start:
post:
tags: [Embedded Services]
summary: Toggle CLIProxyAPI auto-start
description: >-
When enabled, CLIProxyAPI starts automatically on the next OmniRoute boot.
**LOCAL_ONLY** — loopback only.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled]
properties:
enabled:
type: boolean
responses:
"200":
description: Auto-start flag updated
content:
application/json:
schema:
type: object
properties:
autoStart:
type: boolean
"400":
description: Invalid request body
/api/services/{name}/logs:
get:
tags: [Embedded Services]
summary: Stream service logs via SSE
description: >-
Returns a Server-Sent Events stream from the service's in-memory ring buffer
(5 MB, circular). Sends a `snapshot` event with historical lines first, then
live `log` events, plus a `heartbeat` every 15 s.
**LOCAL_ONLY** — loopback only.
parameters:
- name: name
in: path
required: true
schema:
type: string
enum: [9router, cliproxy]
- name: tail
in: query
schema:
type: integer
default: 200
maximum: 1000
description: Number of historical lines to include in the initial snapshot
- name: filter
in: query
schema:
type: string
maxLength: 200
description: >-
Case-insensitive substring filter applied to log lines.
No regex — ReDoS-safe by design.
responses:
"200":
description: SSE log stream
content:
text/event-stream:
schema:
type: string
description: >-
Events: `snapshot` (LogLine[]), `log` (LogLine), `heartbeat` ({})
"400":
description: filter parameter exceeds maximum length
"404":
description: Service not found
# ─── OAuth ─────────────────────────────────────────────────────
/api/oauth/{provider}/{action}:
get:
tags: [OAuth]
summary: OAuth flow handler
description: Handles OAuth authorization and callback for providers
parameters:
- name: provider
in: path
required: true
schema:
type: string
- name: action
in: path
required: true
schema:
type: string
enum: [authorize, callback, refresh, status]
responses:
"200":
description: OAuth flow response
"302":
description: Redirect to provider auth page
/api/oauth/cursor/auto-import:
get:
tags: [OAuth]
summary: Auto-import Cursor OAuth credentials
description: Automatically detects and imports Cursor credentials from local config.
responses:
"200":
description: Import result
/api/oauth/cursor/import:
get:
tags: [OAuth]
summary: Get Cursor import status
responses:
"200":
description: Current import status
post:
tags: [OAuth]
summary: Import Cursor OAuth credentials
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Credentials imported
/api/oauth/kiro/auto-import:
get:
tags: [OAuth]
summary: Auto-import Kiro OAuth credentials
description: Automatically detects and imports Kiro credentials from local config.
responses:
"200":
description: Import result
/api/oauth/kiro/import:
get:
tags: [OAuth]
summary: Get Kiro import status
responses:
"200":
description: Current import status
post:
tags: [OAuth]
summary: Import Kiro OAuth credentials
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Credentials imported
/api/oauth/kiro/social-authorize:
get:
tags: [OAuth]
summary: Initiate Kiro social OAuth authorization
description: Starts the social OAuth flow for Kiro.
responses:
"302":
description: Redirect to OAuth provider
/api/oauth/kiro/social-exchange:
post:
tags: [OAuth]
summary: Exchange Kiro social OAuth token
description: Exchanges the authorization code for access tokens.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Token exchange result
# ─── Cloud ─────────────────────────────────────────────────────
/api/cloud/auth:
post:
tags: [Cloud]
summary: Authenticate with cloud worker
description: Authenticates with the OmniRoute cloud worker for remote access.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Authentication result
/api/cloud/credentials/update:
put:
tags: [Cloud]
summary: Update cloud worker credentials
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Credentials updated
/api/cloud/model/resolve:
post:
tags: [Cloud]
summary: Resolve model via cloud
description: Resolves a model request through the cloud worker.
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Resolved model info
/api/cloud/models/alias:
get:
tags: [Cloud]
summary: Get cloud model aliases
responses:
"200":
description: Cloud model alias list
put:
tags: [Cloud]
summary: Update cloud model alias
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Alias updated
# ─── Fallback ──────────────────────────────────────────────────
/api/fallback/chains:
get:
tags: [Fallback]
summary: List fallback chains
description: Returns all registered fallback chains for model routing.
responses:
"200":
description: Fallback chain list
post:
tags: [Fallback]
summary: Create fallback chain
description: Registers a fallback routing chain for a model.
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [model, chain]
properties:
model:
type: string
chain:
type: array
items:
type: object
properties:
provider:
type: string
priority:
type: integer
enabled:
type: boolean
responses:
"200":
description: Fallback chain created
delete:
tags: [Fallback]
summary: Delete fallback chain
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [model]
properties:
model:
type: string
responses:
"200":
description: Fallback chain deleted
# ─── System ────────────────────────────────────────────────────
/api/auth/login:
post:
tags: [System]
summary: Authenticate user
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [password]
properties:
password:
type: string
responses:
"200":
description: JWT token returned
"401":
description: Invalid password
/api/auth/logout:
post:
tags: [System]
summary: Log out
responses:
"200":
description: Session cleared
/api/init:
get:
tags: [System]
summary: Initialize application
responses:
"200":
description: Init status
/api/restart:
post:
tags: [System]
summary: Restart the application
responses:
"200":
description: Restart initiated
/api/shutdown:
post:
tags: [System]
summary: Shutdown the application
x-always-protected: true
responses:
"200":
description: Shutdown initiated
/api/db-backups:
get:
tags: [System]
summary: List database backups
responses:
"200":
description: Backup list
post:
tags: [System]
summary: Create database backup
responses:
"200":
description: Backup created
/api/storage/health:
get:
tags: [System]
summary: Check storage health
responses:
"200":
description: Storage health status
/api/sync/cloud:
post:
tags: [System]
summary: Sync with cloud
responses:
"200":
description: Sync result
/api/sync/initialize:
post:
tags: [System]
summary: Initialize cloud sync
responses:
"200":
description: Sync initialized
# ─── Resilience & Monitoring ────────────────────────────────────
/api/resilience:
get:
tags: [System]
summary: Get resilience configuration
responses:
"200":
description: Request queue, connection cooldown, provider breaker, and wait settings
patch:
tags: [System]
summary: Update resilience configuration
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated resilience configuration
/api/resilience/reset:
post:
tags: [System]
summary: Reset circuit breakers
responses:
"200":
description: Circuit breakers reset
/api/monitoring/health:
get:
tags: [System]
summary: System health check
description: Returns system health including uptime, memory, circuit breakers, rate limits
responses:
"200":
description: Health status
/api/rate-limits:
get:
tags: [System]
summary: Get per-account rate limit status
responses:
"200":
description: Rate limit status by account
/api/sessions:
get:
tags: [System]
summary: Get active sessions
responses:
"200":
description: Active session list
/api/cache:
get:
tags: [System]
summary: Get cache statistics
responses:
"200":
description: Semantic cache and idempotency stats
delete:
tags: [System]
summary: Clear all caches
responses:
"200":
description: Caches cleared
/api/cache/stats:
get:
tags: [System]
summary: Get detailed cache statistics
description: Returns detailed statistics for all cache layers.
responses:
"200":
description: Detailed cache stats
delete:
tags: [System]
summary: Clear cache statistics
responses:
"200":
description: Cache stats cleared
# ─── Telemetry & Token Health ───────────────────────────────────
/api/telemetry/summary:
get:
tags: [Telemetry]
summary: Get telemetry summary
description: Returns aggregated telemetry data including request metrics and performance stats.
responses:
"200":
description: Telemetry summary data
/api/token-health:
get:
tags: [Telemetry]
summary: Get token health status
description: Returns health status of OAuth tokens across all providers.
responses:
"200":
description: Token health status
# ─── Evals & Policies ──────────────────────────────────────────
/api/evals:
get:
tags: [System]
summary: List eval suites
responses:
"200":
description: Eval suite list
post:
tags: [System]
summary: Run evaluation
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Eval results
/api/evals/{suiteId}:
get:
tags: [System]
summary: Get eval suite details
parameters:
- name: suiteId
in: path
required: true
schema:
type: string
responses:
"200":
description: Eval suite details
/api/policies:
get:
tags: [System]
summary: List routing policies
responses:
"200":
description: Policy list
post:
tags: [System]
summary: Create routing policy
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"201":
description: Created policy
delete:
tags: [System]
summary: Delete routing policy
responses:
"200":
description: Policy deleted
/api/compliance/audit-log:
get:
tags: [System]
summary: Get compliance audit log
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
# ─── AgentBridge ──────────────────────────────────────────────
/api/tools/agent-bridge/agents:
get:
tags: [AgentBridge]
summary: List all 9 IDE agents with current state
description: >-
Returns the state (dns_enabled, cert_trusted, setup_completed, last_started_at,
last_error) for all 9 configured IDE agents. LOCAL_ONLY.
responses:
"200":
description: Array of agent state rows
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AgentBridgeAgentState"
"403":
description: Loopback-only — request came from a non-loopback address
/api/tools/agent-bridge/state:
get:
tags: [AgentBridge]
summary: Get global AgentBridge server state
description: Returns running status, port, cert info, and intercepted request count.
responses:
"200":
description: Server state
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeServerState"
/api/tools/agent-bridge/server:
post:
tags: [AgentBridge]
summary: Control AgentBridge MITM server
description: Start, stop, restart, trust-cert, or regenerate-cert. SPAWN_CAPABLE.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeServerAction"
responses:
"200":
description: Action executed
"400":
description: Invalid action
"409":
description: Port 443 conflict
/api/tools/agent-bridge/agents/{agentId}/state:
get:
tags: [AgentBridge]
summary: Get state of one agent
parameters:
- name: agentId
in: path
required: true
schema:
$ref: "#/components/schemas/AgentId"
responses:
"200":
description: Agent state
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeAgentState"
"404":
description: Unknown agent ID
/api/tools/agent-bridge/agents/{agentId}/dns:
post:
tags: [AgentBridge]
summary: Enable or disable DNS for one agent
description: Adds or removes /etc/hosts entries for the agent's host list. SPAWN_CAPABLE.
parameters:
- name: agentId
in: path
required: true
schema:
$ref: "#/components/schemas/AgentId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeDnsAction"
responses:
"200":
description: DNS updated
"400":
description: Validation error
/api/tools/agent-bridge/agents/{agentId}/mappings:
get:
tags: [AgentBridge]
summary: Get model mappings for one agent
parameters:
- name: agentId
in: path
required: true
schema:
$ref: "#/components/schemas/AgentId"
responses:
"200":
description: Array of source→target model mappings
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AgentBridgeMappingRow"
put:
tags: [AgentBridge]
summary: Update model mappings for one agent
parameters:
- name: agentId
in: path
required: true
schema:
$ref: "#/components/schemas/AgentId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeMappingPut"
responses:
"200":
description: Mappings updated
/api/tools/agent-bridge/bypass:
get:
tags: [AgentBridge]
summary: List bypass patterns (hosts never decrypted)
responses:
"200":
description: Bypass patterns
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AgentBridgeBypassRow"
put:
tags: [AgentBridge]
summary: Update user bypass patterns
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeBypassUpsert"
responses:
"200":
description: Patterns updated
/api/tools/agent-bridge/cert:
post:
tags: [AgentBridge]
summary: Download or regenerate the AgentBridge CA certificate
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [action]
properties:
action:
type: string
enum: [download, regenerate]
responses:
"200":
description: CA certificate PEM (download) or regeneration confirmation
/api/tools/agent-bridge/upstream-ca:
get:
tags: [AgentBridge]
summary: Get configured upstream CA cert path
responses:
"200":
description: Upstream CA configuration
content:
application/json:
schema:
type: object
properties:
path:
type: string
nullable: true
post:
tags: [AgentBridge]
summary: Set upstream CA cert path for corporate TLS environments
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AgentBridgeUpstreamCaPost"
responses:
"200":
description: Upstream CA configured
"400":
description: Path does not exist or is not readable
# ─── Traffic Inspector ─────────────────────────────────────────
/api/tools/traffic-inspector/requests:
get:
tags: [Traffic Inspector]
summary: List intercepted requests (filterable)
parameters:
- name: profile
in: query
schema:
type: string
enum: [llm, custom, all]
- name: host
in: query
schema:
type: string
- name: agent
in: query
schema:
$ref: "#/components/schemas/AgentId"
- name: status
in: query
schema:
type: string
enum: ["2xx", "3xx", "4xx", "5xx", error]
- name: source
in: query
schema:
$ref: "#/components/schemas/CaptureSource"
- name: sessionId
in: query
schema:
type: string
format: uuid
responses:
"200":
description: Array of intercepted requests
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/InterceptedRequest"
delete:
tags: [Traffic Inspector]
summary: Clear the in-memory traffic buffer
responses:
"204":
description: Buffer cleared
/api/tools/traffic-inspector/requests/{id}:
get:
tags: [Traffic Inspector]
summary: Get a single intercepted request by ID
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Intercepted request details
content:
application/json:
schema:
$ref: "#/components/schemas/InterceptedRequest"
"404":
description: Request not found in buffer
/api/tools/traffic-inspector/requests/{id}/replay:
post:
tags: [Traffic Inspector]
summary: Replay a captured request through OmniRoute router
description: Re-executes the original request body against /v1/chat/completions. Consumes quota.
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Replay response (streaming or JSON)
"404":
description: Request not found
/api/tools/traffic-inspector/requests/{id}/annotation:
put:
tags: [Traffic Inspector]
summary: Save or update annotation on a request
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorAnnotationPut"
responses:
"200":
description: Annotation saved
/api/tools/traffic-inspector/ws:
get:
tags: [Traffic Inspector]
summary: Live WebSocket stream of intercepted requests
description: >-
Upgrade to WebSocket. On connect, server sends `{type:"snapshot", data:[...]}`.
Subsequent events: `{type:"new", data:{...}}`, `{type:"update", data:{...}}`,
`{type:"clear"}`. LOCAL_ONLY.
responses:
"101":
description: WebSocket upgrade successful
"403":
description: Non-loopback origin rejected
/api/tools/traffic-inspector/export.har:
get:
tags: [Traffic Inspector]
summary: Export current filtered request list as HAR 1.2
parameters:
- name: profile
in: query
schema:
type: string
enum: [llm, custom, all]
- name: sessionId
in: query
schema:
type: string
format: uuid
responses:
"200":
description: HAR file (JSON)
content:
application/json:
schema:
type: object
description: HAR 1.2 format
/api/tools/traffic-inspector/hosts:
get:
tags: [Traffic Inspector]
summary: List custom capture hosts
responses:
"200":
description: Custom hosts list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/InspectorCustomHost"
post:
tags: [Traffic Inspector]
summary: Add a custom capture host (edits /etc/hosts)
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorCustomHostCreate"
responses:
"201":
description: Host added
"409":
description: Host already exists
/api/tools/traffic-inspector/hosts/{host}:
delete:
tags: [Traffic Inspector]
summary: Remove a custom capture host
parameters:
- name: host
in: path
required: true
schema:
type: string
responses:
"204":
description: Host removed
patch:
tags: [Traffic Inspector]
summary: Toggle enabled state of a custom host
parameters:
- name: host
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled]
properties:
enabled:
type: boolean
responses:
"200":
description: Host updated
/api/tools/traffic-inspector/capture-modes:
get:
tags: [Traffic Inspector]
summary: Get state of all 4 capture modes
responses:
"200":
description: Capture modes state
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorCaptureModesState"
/api/tools/traffic-inspector/capture-modes/http-proxy:
post:
tags: [Traffic Inspector]
summary: Start or stop the HTTP_PROXY listener (port 8080)
description: SPAWN_CAPABLE — spawns a net.Server listener.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorCaptureModeAction"
responses:
"200":
description: Action executed
"409":
description: Port conflict (EADDRINUSE) when starting
/api/tools/traffic-inspector/capture-modes/system-proxy:
post:
tags: [Traffic Inspector]
summary: Apply or revert system-wide proxy settings
description: SPAWN_CAPABLE — executes networksetup/gsettings/netsh. Requires admin.
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorSystemProxyAction"
responses:
"200":
description: System proxy updated
"500":
description: OS command failed (permission error)
/api/tools/traffic-inspector/capture-modes/tls-intercept:
post:
tags: [Traffic Inspector]
summary: Toggle TLS body decryption in HTTP_PROXY mode
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorTlsInterceptToggle"
responses:
"200":
description: TLS intercept mode updated
/api/tools/traffic-inspector/sessions:
get:
tags: [Traffic Inspector]
summary: List all saved recording sessions
responses:
"200":
description: Sessions list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/InspectorSession"
post:
tags: [Traffic Inspector]
summary: Start a new recording session
requestBody:
required: false
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorSessionStart"
responses:
"201":
description: Session started
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorSession"
/api/tools/traffic-inspector/sessions/{id}:
get:
tags: [Traffic Inspector]
summary: Get session snapshot (all captured requests)
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: Session with embedded requests
"404":
description: Session not found
patch:
tags: [Traffic Inspector]
summary: Stop or rename a recording session
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InspectorSessionPatch"
responses:
"200":
description: Session updated
delete:
tags: [Traffic Inspector]
summary: Delete a recording session
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"204":
description: Session deleted
/api/tools/traffic-inspector/sessions/{id}/export.har:
get:
tags: [Traffic Inspector]
summary: Export a recorded session as HAR 1.2
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
responses:
"200":
description: HAR file for this session
content:
application/json:
schema:
type: object
description: HAR 1.2 format
"404":
description: Session not found
/api/tools/traffic-inspector/internal/ingest:
post:
tags: [Traffic Inspector]
summary: Internal ingest endpoint for server.cjs passthrough path
description: >-
Accepts a serialized InterceptedRequest from the CJS MITM server for requests
that do not go through TypeScript handlers (e.g., passthrough hosts). Requires
INSPECTOR_INTERNAL_INGEST_TOKEN header. LOCAL_ONLY.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InterceptedRequest"
responses:
"204":
description: Ingested
"401":
description: Invalid or missing ingest token
# ─── OpenAPI Spec ──────────────────────────────────────────────
/api/openapi/spec:
get:
tags: [System]
summary: Get OpenAPI specification catalog
description: >-
Returns a structured JSON catalog parsed from this `openapi.yaml`,
including info, servers, tags, schemas, and a flat list of endpoints
(method, path, tags, summary, security, parameters, responses).
Used by the in-app API explorer.
responses:
"200":
description: Parsed OpenAPI catalog
content:
application/json:
schema:
type: object
properties:
info:
type: object
servers:
type: array
items:
type: object
tags:
type: array
items:
type: object
endpoints:
type: array
items:
type: object
properties:
method:
type: string
path:
type: string
tags:
type: array
items:
type: string
summary:
type: string
description:
type: string
security:
type: boolean
parameters:
type: array
items:
type: object
requestBody:
type: boolean
responses:
type: array
items:
type: string
schemas:
type: array
items:
type: string
"404":
description: openapi.yaml file not found on disk
"500":
description: Failed to parse OpenAPI spec
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: API key obtained from the OmniRoute dashboard
ManagementSessionAuth:
type: apiKey
in: cookie
name: auth_token
description: Dashboard management session cookie for protected management routes
parameters:
ResourceId:
name: id
in: path
required: true
schema:
type: string
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Unauthorized
ManagementAuthenticationRequired:
description: Authentication required for management routes
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error:
message: Authentication required
type: invalid_request
requestId: 3f9f6f5a-509a-4b35-b0a7-2d2d99d73a01
ManagementInvalidToken:
description: Bearer tokens are not accepted for management routes
content:
application/json:
schema:
$ref: "#/components/schemas/ApiErrorResponse"
example:
error:
message: Invalid management token
type: invalid_request
requestId: 1b6a6ff8-d60c-4900-8d0a-25f81749f0a3
ValidationError:
description: Request body failed validation
content:
application/json:
schema:
$ref: "#/components/schemas/ValidationErrorResponse"
schemas:
# ─── AgentBridge Schemas ────────────────────────────────────────
AgentId:
type: string
enum:
- antigravity
- kiro
- copilot
- codex
- cursor
- zed
- claude-code
- open-code
- trae
description: One of the 9 supported IDE agents
AgentBridgeAgentState:
type: object
description: Per-agent MITM state
properties:
agent_id:
$ref: "#/components/schemas/AgentId"
dns_enabled:
type: boolean
cert_trusted:
type: boolean
setup_completed:
type: boolean
last_started_at:
type: string
format: date-time
nullable: true
last_error:
type: string
nullable: true
AgentBridgeServerState:
type: object
description: Global AgentBridge MITM server state
properties:
running:
type: boolean
port:
type: integer
example: 443
certReady:
type: boolean
interceptedCount:
type: integer
activeConnections:
type: integer
lastStartedAt:
type: string
format: date-time
nullable: true
AgentBridgeServerAction:
type: object
required: [action]
properties:
action:
type: string
enum: [start, stop, restart, trust-cert, regenerate-cert]
AgentBridgeDnsAction:
type: object
required: [enabled]
properties:
enabled:
type: boolean
AgentBridgeMappingRow:
type: object
properties:
agent_id:
$ref: "#/components/schemas/AgentId"
source_model:
type: string
example: gpt-4o
target_model:
type: string
example: claude-sonnet-4.7
updated_at:
type: string
format: date-time
AgentBridgeMappingPut:
type: object
required: [mappings]
properties:
mappings:
type: array
items:
type: object
required: [source, target]
properties:
source:
type: string
example: gpt-4o
target:
type: string
example: claude-sonnet-4.7
AgentBridgeBypassRow:
type: object
properties:
pattern:
type: string
example: "*.bank.*"
source:
type: string
enum: [default, user]
created_at:
type: string
format: date-time
AgentBridgeBypassUpsert:
type: object
required: [patterns]
properties:
patterns:
type: array
items:
type: string
example: ["*.bank.*", "*.gov.*"]
AgentBridgeUpstreamCaPost:
type: object
required: [path]
properties:
path:
type: string
description: Absolute path to a PEM file for corporate upstream CA
example: "/etc/ssl/certs/corporate-ca.pem"
# ─── Traffic Inspector Schemas ──────────────────────────────────
CaptureSource:
type: string
enum: [agent-bridge, custom-host, http-proxy, system-proxy]
DetectedKind:
type: string
enum: [llm, app, unknown]
InterceptedRequest:
type: object
description: A single intercepted HTTP request captured by the Traffic Inspector
required: [id, source, timestamp, method, host, path, requestHeaders, requestSize, responseHeaders, responseSize, status]
properties:
id:
type: string
format: uuid
source:
$ref: "#/components/schemas/CaptureSource"
agent:
$ref: "#/components/schemas/AgentId"
timestamp:
type: string
format: date-time
method:
type: string
example: POST
host:
type: string
example: api.githubcopilot.com
path:
type: string
example: /v1/chat/completions
requestHeaders:
type: object
additionalProperties:
type: string
requestBody:
type: string
nullable: true
description: Masked (secrets replaced with ***)
requestSize:
type: integer
responseHeaders:
type: object
additionalProperties:
type: string
responseBody:
type: string
nullable: true
responseSize:
type: integer
status:
oneOf:
- type: integer
- type: string
enum: [in-flight, error]
proxyLatencyMs:
type: number
nullable: true
upstreamLatencyMs:
type: number
nullable: true
totalLatencyMs:
type: number
nullable: true
error:
type: string
nullable: true
description: Sanitized error message (no stack traces)
sourceModel:
type: string
nullable: true
mappedModel:
type: string
nullable: true
detectedKind:
$ref: "#/components/schemas/DetectedKind"
contextKey:
type: string
nullable: true
description: 12-char SHA-256 hex of the system prompt (for conversation grouping)
example: a3f9c2b1d5e4
annotation:
type: string
nullable: true
sessionId:
type: string
format: uuid
nullable: true
note:
type: string
nullable: true
description: Informational note (e.g. TLS tunnel metadata)
InspectorCustomHost:
type: object
properties:
host:
type: string
example: api.openai.com
enabled:
type: boolean
label:
type: string
nullable: true
kind:
type: string
enum: [llm, app, custom]
added_at:
type: string
format: date-time
last_seen_at:
type: string
format: date-time
nullable: true
InspectorCustomHostCreate:
type: object
required: [host]
properties:
host:
type: string
minLength: 1
example: my-internal-llm.company.com
enabled:
type: boolean
default: true
label:
type: string
nullable: true
kind:
type: string
enum: [llm, app, custom]
default: custom
InspectorCaptureModesState:
type: object
properties:
agentBridge:
type: object
properties:
active:
type: boolean
customHosts:
type: object
properties:
active:
type: boolean
count:
type: integer
httpProxy:
type: object
properties:
active:
type: boolean
port:
type: integer
example: 8080
systemProxy:
type: object
properties:
active:
type: boolean
guardMinutes:
type: integer
InspectorCaptureModeAction:
type: object
required: [action]
properties:
action:
type: string
enum: [start, stop]
InspectorSystemProxyAction:
type: object
required: [action]
properties:
action:
type: string
enum: [apply, revert]
port:
type: integer
minimum: 1
maximum: 65535
example: 8080
guardMinutes:
type: integer
minimum: 1
example: 30
InspectorTlsInterceptToggle:
type: object
required: [enabled]
properties:
enabled:
type: boolean
InspectorAnnotationPut:
type: object
required: [annotation]
properties:
annotation:
type: string
maxLength: 10000
InspectorSession:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
nullable: true
started_at:
type: string
format: date-time
ended_at:
type: string
format: date-time
nullable: true
request_count:
type: integer
profile:
type: string
enum: [llm, custom, all]
nullable: true
InspectorSessionStart:
type: object
properties:
name:
type: string
example: "Antigravity test run #1"
InspectorSessionPatch:
type: object
required: [action]
properties:
action:
type: string
enum: [stop, rename]
name:
type: string
ServiceStatus:
type: object
description: Live supervisor state for an embedded service
properties:
tool:
type: string
example: 9router
state:
type: string
enum: [not_installed, stopped, starting, running, stopping, error]
pid:
type: integer
nullable: true
port:
type: integer
example: 20130
health:
type: string
enum: [unknown, healthy, degraded]
startedAt:
type: string
format: date-time
nullable: true
lastError:
type: string
nullable: true
ServiceStatusExtended:
allOf:
- $ref: "#/components/schemas/ServiceStatus"
- type: object
description: >-
Extended status including version metadata and (for 9Router) API key preview.
properties:
installedVersion:
type: string
nullable: true
latestVersion:
type: string
nullable: true
updateAvailable:
type: boolean
apiKeyMasked:
type: string
nullable: true
description: >-
Masked API key preview (e.g. "nr_****abcd").
Present only for services that use an injected API key (9Router).
autoStart:
type: boolean
providerExpose:
type: boolean
description: >-
Whether models from this service are exposed as a routing provider.
9Router only.
ApiErrorResponse:
type: object
properties:
error:
type: object
properties:
message:
type: string
type:
type: string
details:
description: Optional additional error details
requestId:
type: string
format: uuid
ValidationErrorResponse:
type: object
properties:
error:
type: object
required: [message, details]
properties:
message:
type: string
example: Invalid request
details:
type: array
items:
type: object
required: [field, message]
properties:
field:
type: string
message:
type: string
PayloadRuleModelSpec:
type: object
additionalProperties: false
required: [name]
properties:
name:
type: string
minLength: 1
protocol:
type: string
minLength: 1
PayloadMutationRule:
type: object
additionalProperties: false
required: [models, params]
properties:
models:
type: array
minItems: 1
items:
$ref: "#/components/schemas/PayloadRuleModelSpec"
params:
type: object
minProperties: 1
additionalProperties: true
PayloadFilterRule:
type: object
additionalProperties: false
required: [models, params]
properties:
models:
type: array
minItems: 1
items:
$ref: "#/components/schemas/PayloadRuleModelSpec"
params:
type: array
minItems: 1
items:
type: string
minLength: 1
PayloadRulesConfig:
type: object
additionalProperties: false
required: [default, override, filter, defaultRaw]
properties:
default:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
override:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
filter:
type: array
items:
$ref: "#/components/schemas/PayloadFilterRule"
defaultRaw:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
UpdatePayloadRulesRequest:
type: object
additionalProperties: false
description: At least one payload-rules section must be present in the request body.
properties:
default:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
override:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
filter:
type: array
items:
$ref: "#/components/schemas/PayloadFilterRule"
defaultRaw:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
default-raw:
type: array
items:
$ref: "#/components/schemas/PayloadMutationRule"
anyOf:
- required: [default]
- required: [override]
- required: [filter]
- required: [defaultRaw]
- required: [default-raw]
ChatCompletionRequest:
type: object
required: [model, messages]
properties:
model:
type: string
example: gpt-4o
messages:
type: array
items:
type: object
required: [role]
properties:
role:
type: string
description: >-
Message role. The proxy accepts any non-empty string; common values
include system, user, assistant, tool, function, and developer.
example: user
content:
description: >-
Message content. May be a plain string, an array of content parts
for multimodal inputs (text, image, audio, etc.), or null when the
message only carries tool/function calls.
oneOf:
- type: string
- type: array
items:
type: object
- type: "null"
name:
type: string
tool_call_id:
type: string
tool_calls:
type: array
items:
type: object
function_call:
type: object
stream:
type: boolean
default: false
temperature:
type: number
minimum: 0
maximum: 2
max_tokens:
type: integer
top_p:
type: number
minimum: 0
maximum: 1
n:
type: integer
minimum: 1
default: 1
stop:
description: Up to 4 stop sequences (string or array of strings).
oneOf:
- type: string
- type: array
items:
type: string
maxItems: 4
frequency_penalty:
type: number
minimum: -2
maximum: 2
presence_penalty:
type: number
minimum: -2
maximum: 2
seed:
type: integer
logprobs:
type: boolean
top_logprobs:
type: integer
minimum: 0
maximum: 20
response_format:
type: object
description: Output format constraint (e.g. JSON mode or JSON Schema).
properties:
type:
type: string
example: json_object
tools:
type: array
description: Tool definitions available to the model.
items:
type: object
tool_choice:
description: Controls which tool (if any) is invoked by the model.
oneOf:
- type: string
example: auto
- type: object
parallel_tool_calls:
type: boolean
default: true
service_tier:
type: string
example: auto
user:
type: string
description: Stable end-user identifier for abuse monitoring.
ChatCompletionResponse:
type: object
properties:
id:
type: string
object:
type: string
example: chat.completion
choices:
type: array
items:
type: object
properties:
index:
type: integer
message:
type: object
properties:
role:
type: string
content:
type: string
finish_reason:
type: string
usage:
type: object
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
MessagesRequest:
type: object
required: [model, messages, max_tokens]
properties:
model:
type: string
example: claude-sonnet-4-5-20250514
messages:
type: array
items:
type: object
required: [role, content]
properties:
role:
type: string
enum: [user, assistant]
content:
type: string
max_tokens:
type: integer
stream:
type: boolean
default: false
system:
type: string
Model:
type: object
properties:
id:
type: string
object:
type: string
example: model
owned_by:
type: string
ProviderConnection:
type: object
properties:
id:
type: string
provider:
type: string
name:
type: string
url:
type: string
isActive:
type: boolean
maxConcurrent:
type: integer
nullable: true
minimum: 0
priority:
type: integer
testStatus:
type: string
enum: [active, error, untested]
createdAt:
type: string
format: date-time
ProviderConnectionCreate:
type: object
required: [provider, url]
properties:
provider:
type: string
example: openai
name:
type: string
url:
type: string
apiKey:
type: string
isActive:
type: boolean
default: true
maxConcurrent:
type: integer
nullable: true
minimum: 0
ApiKey:
type: object
properties:
id:
type: string
label:
type: string
keyPreview:
type: string
description: Last 4 characters of the key
isActive:
type: boolean
createdAt:
type: string
format: date-time
ComboCreate:
type: object
required: [name, model]
properties:
name:
type: string
model:
type: string
strategy:
type: string
enum:
- priority
- weighted
- round-robin
- context-relay
- fill-first
- p2c
- random
- least-used
- cost-optimized
- reset-aware
- strict-random
- auto
- lkgp
- context-optimized
default: priority
nodes:
type: array
items:
type: object
properties:
connectionId:
type: string
weight:
type: integer
priority:
type: integer