mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-26 09:52:11 +03:00
a086862c97
Update the main and localized changelogs with the 3.8.7 release notes, including new API self-service status, analytics retention, RAM optimizations, and token accounting fixes. Clarify release skill instructions to ensure new release branches are always created from the latest main branch.
3299 lines
87 KiB
YAML
3299 lines
87 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: OmniRoute API
|
|
version: 3.8.7
|
|
description: |
|
|
OmniRoute is a local-first AI API proxy router. It provides an OpenAI-compatible
|
|
endpoint that routes requests to multiple AI providers with load balancing,
|
|
failover, and usage tracking.
|
|
|
|
## Base URLs
|
|
- **Local**: `http://localhost:20128`
|
|
|
|
## Authentication
|
|
All proxy endpoints require a Bearer token (API key managed via the dashboard).
|
|
Management endpoints are protected when `requireLogin` is enabled.
|
|
contact:
|
|
name: OmniRoute
|
|
license:
|
|
name: MIT
|
|
|
|
servers:
|
|
- url: http://localhost:20128
|
|
description: Local development
|
|
|
|
tags:
|
|
- name: Chat
|
|
description: OpenAI-compatible chat completions
|
|
- name: Messages
|
|
description: Anthropic-compatible messages
|
|
- name: Responses
|
|
description: OpenAI Responses API
|
|
- name: Embeddings
|
|
description: Text embedding generation
|
|
- name: Images
|
|
description: Image generation
|
|
- name: Audio
|
|
description: Audio speech and transcription
|
|
- name: Moderations
|
|
description: Content moderation
|
|
- name: Rerank
|
|
description: Document reranking
|
|
- name: Models
|
|
description: Available model listing
|
|
- name: Providers
|
|
description: Provider connection management
|
|
- name: Provider Nodes
|
|
description: Provider node configuration
|
|
- name: API Keys
|
|
description: API key management
|
|
- name: Combos
|
|
description: Routing combo management
|
|
- name: Settings
|
|
description: Application settings
|
|
- name: Compression
|
|
description: Prompt compression, RTK filters, Caveman rules, and compression combos
|
|
- name: Usage
|
|
description: Usage analytics and logs
|
|
- name: Translator
|
|
description: Format translation debug & testing
|
|
- name: CLI Tools
|
|
description: CLI tool configuration management
|
|
- name: Embedded Services
|
|
description: >-
|
|
Install, start, stop, and monitor locally-running embedded services (9Router, CLIProxyAPI).
|
|
All routes are LOCAL_ONLY — accessible from loopback only (hard rule #17).
|
|
- name: OAuth
|
|
description: OAuth flows for provider authentication
|
|
- name: System
|
|
description: System management (restart, shutdown, backup)
|
|
- name: Pricing
|
|
description: Model pricing configuration
|
|
- name: Cloud
|
|
description: Cloud worker authentication and sync
|
|
- name: Fallback
|
|
description: Fallback chain management
|
|
- name: Telemetry
|
|
description: Telemetry and token health monitoring
|
|
|
|
paths:
|
|
# ─── Proxy Endpoints ──────────────────────────────────────────
|
|
|
|
/api/v1/chat/completions:
|
|
post:
|
|
tags: [Chat]
|
|
summary: Create chat completion
|
|
description: OpenAI-compatible chat completions endpoint. Routes to configured providers.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ChatCompletionRequest"
|
|
responses:
|
|
"200":
|
|
description: Chat completion response (or SSE stream)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ChatCompletionResponse"
|
|
text/event-stream:
|
|
schema:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"502":
|
|
description: All upstream providers failed
|
|
|
|
/api/v1/providers/{provider}/chat/completions:
|
|
post:
|
|
tags: [Chat]
|
|
summary: Create chat completion (provider-specific)
|
|
description: Routes to a specific provider by name.
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: provider
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ChatCompletionRequest"
|
|
responses:
|
|
"200":
|
|
description: Chat completion response
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/v1/api/chat:
|
|
post:
|
|
tags: [Chat]
|
|
summary: Ollama-compatible chat endpoint
|
|
description: Provides compatibility with Ollama's /api/chat format.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Chat response (JSON or streaming)
|
|
|
|
/api/v1/messages:
|
|
post:
|
|
tags: [Messages]
|
|
summary: Create message (Anthropic-compatible)
|
|
description: Anthropic Messages API endpoint. Routes to Claude providers.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MessagesRequest"
|
|
responses:
|
|
"200":
|
|
description: Message response (or SSE stream)
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/v1/messages/count_tokens:
|
|
post:
|
|
tags: [Messages]
|
|
summary: Count tokens for a message
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Token count
|
|
|
|
/api/v1/responses:
|
|
post:
|
|
tags: [Responses]
|
|
summary: Create response (OpenAI Responses API)
|
|
description: OpenAI Responses API endpoint.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Response object or SSE stream
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/v1/embeddings:
|
|
post:
|
|
tags: [Embeddings]
|
|
summary: Create embeddings
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [input, model]
|
|
properties:
|
|
input:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: string
|
|
model:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Embedding vectors
|
|
|
|
/api/v1/providers/{provider}/embeddings:
|
|
post:
|
|
tags: [Embeddings]
|
|
summary: Create embeddings (provider-specific)
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: provider
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Embedding vectors
|
|
|
|
/api/v1/images/generations:
|
|
post:
|
|
tags: [Images]
|
|
summary: Generate images
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [prompt]
|
|
properties:
|
|
prompt:
|
|
type: string
|
|
model:
|
|
type: string
|
|
n:
|
|
type: integer
|
|
default: 1
|
|
size:
|
|
type: string
|
|
default: 1024x1024
|
|
responses:
|
|
"200":
|
|
description: Generated images
|
|
|
|
/api/v1/providers/{provider}/images/generations:
|
|
post:
|
|
tags: [Images]
|
|
summary: Generate images (provider-specific)
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: provider
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Generated images
|
|
|
|
/api/v1/audio/speech:
|
|
post:
|
|
tags: [Audio]
|
|
summary: Generate speech audio
|
|
description: Text-to-speech endpoint. Routes to configured TTS providers.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [input]
|
|
properties:
|
|
input:
|
|
type: string
|
|
model:
|
|
type: string
|
|
voice:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Audio data
|
|
|
|
/api/v1/audio/transcriptions:
|
|
post:
|
|
tags: [Audio]
|
|
summary: Transcribe audio
|
|
description: Audio-to-text transcription endpoint.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required: [file]
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
model:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Transcription result
|
|
|
|
/api/v1/moderations:
|
|
post:
|
|
tags: [Moderations]
|
|
summary: Create moderation
|
|
description: Content moderation endpoint. Routes to configured moderation providers.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [input]
|
|
properties:
|
|
input:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Moderation result
|
|
|
|
/api/v1/rerank:
|
|
post:
|
|
tags: [Rerank]
|
|
summary: Rerank documents
|
|
description: Document reranking endpoint.
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [query, documents]
|
|
properties:
|
|
query:
|
|
type: string
|
|
documents:
|
|
type: array
|
|
items:
|
|
type: string
|
|
model:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Reranked documents
|
|
|
|
/api/v1:
|
|
get:
|
|
tags: [System]
|
|
summary: API v1 root endpoint
|
|
description: Returns basic API info and status.
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
"200":
|
|
description: API info
|
|
|
|
/api/v1/models:
|
|
get:
|
|
tags: [Models]
|
|
summary: List available models
|
|
description: Returns all models available across configured providers.
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
"200":
|
|
description: Model list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
object:
|
|
type: string
|
|
example: list
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Model"
|
|
|
|
/api/v1/providers/{provider}/models:
|
|
get:
|
|
tags: [Models]
|
|
summary: List models for a specific provider
|
|
description: Returns only models for the selected provider with provider prefix removed from each model id.
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- in: path
|
|
name: provider
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Provider id or alias (for example `openai`, `claude`, `cc`).
|
|
responses:
|
|
"200":
|
|
description: Provider-scoped model list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
object:
|
|
type: string
|
|
example: list
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Model"
|
|
"400":
|
|
description: Unknown provider
|
|
|
|
/api/models:
|
|
get:
|
|
tags: [Models]
|
|
summary: List models (management)
|
|
responses:
|
|
"200":
|
|
description: Internal model list with aliases
|
|
|
|
/api/models/alias:
|
|
post:
|
|
tags: [Models]
|
|
summary: Create or update a model alias
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Alias created/updated
|
|
|
|
/api/models/catalog:
|
|
get:
|
|
tags: [Models]
|
|
summary: Get full model catalog
|
|
responses:
|
|
"200":
|
|
description: Complete catalog with all providers
|
|
|
|
# ─── Management Endpoints ──────────────────────────────────────
|
|
|
|
/api/providers:
|
|
get:
|
|
tags: [Providers]
|
|
summary: List provider connections
|
|
responses:
|
|
"200":
|
|
description: Provider connection list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
connections:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ProviderConnection"
|
|
post:
|
|
tags: [Providers]
|
|
summary: Create provider connection
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ProviderConnectionCreate"
|
|
responses:
|
|
"201":
|
|
description: Created provider connection
|
|
|
|
/api/providers/{id}:
|
|
get:
|
|
tags: [Providers]
|
|
summary: Get provider connection
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceId"
|
|
responses:
|
|
"200":
|
|
description: Provider connection details
|
|
"404":
|
|
description: Provider not found
|
|
patch:
|
|
tags: [Providers]
|
|
summary: Update provider connection
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceId"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ProviderConnectionCreate"
|
|
responses:
|
|
"200":
|
|
description: Updated provider
|
|
delete:
|
|
tags: [Providers]
|
|
summary: Delete provider connection
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceId"
|
|
responses:
|
|
"200":
|
|
description: Provider deleted
|
|
|
|
/api/providers/{id}/test:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Test provider connection
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceId"
|
|
responses:
|
|
"200":
|
|
description: Test result
|
|
|
|
/api/providers/{id}/models:
|
|
get:
|
|
tags: [Providers]
|
|
summary: List models for a provider
|
|
parameters:
|
|
- $ref: "#/components/parameters/ResourceId"
|
|
responses:
|
|
"200":
|
|
description: Provider model list
|
|
|
|
/api/providers/test-batch:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Test multiple providers at once
|
|
responses:
|
|
"200":
|
|
description: Batch test results
|
|
|
|
/api/providers/validate:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Validate provider credentials
|
|
responses:
|
|
"200":
|
|
description: Validation result
|
|
|
|
/api/providers/client:
|
|
get:
|
|
tags: [Providers]
|
|
summary: Get client-side provider info
|
|
responses:
|
|
"200":
|
|
description: Provider info for frontend
|
|
|
|
/api/providers/agy-auth/import:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Import an Antigravity CLI (agy) token file as an `agy` connection
|
|
responses:
|
|
"200":
|
|
description: Created or updated provider connection
|
|
|
|
/api/providers/agy-auth/import-bulk:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Bulk-import multiple Antigravity CLI (agy) token files (up to 50)
|
|
responses:
|
|
"200":
|
|
description: Per-entry import results (success/failed counts)
|
|
|
|
/api/providers/agy-auth/zip-extract:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Extract `.json` token files from an uploaded ZIP for agy bulk import
|
|
responses:
|
|
"200":
|
|
description: Extracted token-file entries
|
|
|
|
/api/providers/agy-auth/apply-local:
|
|
post:
|
|
tags: [Providers]
|
|
summary: Auto-detect and import the local Antigravity CLI (agy) login from disk
|
|
responses:
|
|
"200":
|
|
description: Created or updated provider connection
|
|
"404":
|
|
description: No local agy login found
|
|
|
|
/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
|
|
|
|
# ─── 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:
|
|
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
|