mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-07-31 12:22:14 +03:00
517385e789
- Add tests/e2e/memory-engine.spec.ts (7 scenarios: 3-tab render, memories table,
add/edit modal, playground simulate, engine status chips, reindex button)
- Add tests/e2e/memory-qdrant-routes.spec.ts (3 scenarios: Qdrant config card,
Test Connection → sanitized error without stack, Cleanup → sanitized error)
- Update docs/frameworks/MEMORY.md: add Engine architecture (3-tier ASCII diagram),
Embedding sources table, Hybrid RRF (k=60) section, Backfill lazy+reindex section,
Settings extension (7 new fields D9), updated REST API table (10 new routes),
updated Dashboard section (Studio 3 tabs), MCP D16 strategy from settings, See Also
- Update docs/reference/openapi.yaml: add Memory tag + 13 new paths
(/api/memory, /api/memory/{id} PUT, retrieve-preview, embedding-providers,
engine-status, summarize, reindex, /api/settings/memory GET+PUT,
/api/settings/qdrant GET+PUT+health+search+cleanup+embedding-models)
+ MemoryEntry, MemorySettingsExtended, QdrantSettings, QdrantHealthResult schemas
- Update docs/architecture/REPOSITORY_MAP.md: add embedding/, vectorStore.ts,
reindex.ts, memoryVec.ts, memory Studio UI entries
- Sort memory.* namespace keys alphabetically in pt-BR.json and en.json
(no duplicate found — pure reorder, no content change)
- .env.example already has all 7 vars from §3.9 (confirmed, no change needed)
4189 lines
114 KiB
YAML
4189 lines
114 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: Memory
|
|
description: >-
|
|
Conversational memory management — CRUD, engine status, playground preview,
|
|
summarization, reindex, and Qdrant settings (plan 21 — v3.8.6).
|
|
All routes require management auth.
|
|
|
|
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
|
|
|
|
# ─── OpenAPI Spec ──────────────────────────────────────────────
|
|
|
|
/api/openapi/spec:
|
|
get:
|
|
tags: [System]
|
|
summary: Get OpenAPI specification catalog
|
|
description: >-
|
|
Returns a structured JSON catalog parsed from this `openapi.yaml`,
|
|
including info, servers, tags, schemas, and a flat list of endpoints
|
|
(method, path, tags, summary, security, parameters, responses).
|
|
Used by the in-app API explorer.
|
|
responses:
|
|
"200":
|
|
description: Parsed OpenAPI catalog
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
info:
|
|
type: object
|
|
servers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: object
|
|
endpoints:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
method:
|
|
type: string
|
|
path:
|
|
type: string
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
summary:
|
|
type: string
|
|
description:
|
|
type: string
|
|
security:
|
|
type: boolean
|
|
parameters:
|
|
type: array
|
|
items:
|
|
type: object
|
|
requestBody:
|
|
type: boolean
|
|
responses:
|
|
type: array
|
|
items:
|
|
type: string
|
|
schemas:
|
|
type: array
|
|
items:
|
|
type: string
|
|
"404":
|
|
description: openapi.yaml file not found on disk
|
|
"500":
|
|
description: Failed to parse OpenAPI spec
|
|
|
|
# ─── Memory Engine (plan 21 — v3.8.6) ─────────────────────────
|
|
|
|
/api/memory:
|
|
get:
|
|
tags: [Memory]
|
|
summary: List memory entries
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
parameters:
|
|
- name: apiKeyId
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- name: type
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [factual, episodic, procedural, semantic]
|
|
- name: sessionId
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- name: q
|
|
in: query
|
|
schema:
|
|
type: string
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
default: 50
|
|
- name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
responses:
|
|
"200":
|
|
description: Paginated list of memories with stats
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/MemoryEntry"
|
|
total:
|
|
type: integer
|
|
totalPages:
|
|
type: integer
|
|
stats:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
tokensUsed:
|
|
type: integer
|
|
hitRate:
|
|
type: number
|
|
cacheStats:
|
|
type: object
|
|
properties:
|
|
hits:
|
|
type: integer
|
|
misses:
|
|
type: integer
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
post:
|
|
tags: [Memory]
|
|
summary: Create a memory entry
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [content, key]
|
|
properties:
|
|
content:
|
|
type: string
|
|
minLength: 1
|
|
key:
|
|
type: string
|
|
minLength: 1
|
|
type:
|
|
type: string
|
|
enum: [factual, episodic, procedural, semantic]
|
|
default: factual
|
|
sessionId:
|
|
type: string
|
|
nullable: true
|
|
apiKeyId:
|
|
type: string
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
responses:
|
|
"201":
|
|
description: Created memory entry
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemoryEntry"
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/{id}:
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Memory UUID
|
|
get:
|
|
tags: [Memory]
|
|
summary: Get a single memory entry
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Memory entry
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemoryEntry"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Memory not found
|
|
put:
|
|
tags: [Memory]
|
|
summary: Update a memory entry
|
|
description: >-
|
|
Update `type`, `key`, `content`, and/or `metadata` of an existing memory.
|
|
If an embedding source is available, the vector in `vec_memories` is also
|
|
regenerated. Corresponds to `MemoryUpdatePutSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [factual, episodic, procedural, semantic]
|
|
key:
|
|
type: string
|
|
minLength: 1
|
|
content:
|
|
type: string
|
|
minLength: 1
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Updated memory entry
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemoryEntry"
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Memory not found
|
|
delete:
|
|
tags: [Memory]
|
|
summary: Delete a memory entry
|
|
description: >-
|
|
Deletes the SQLite row, removes the vector from `vec_memories`, and
|
|
best-effort deletes the point from Qdrant.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Deleted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
description: Memory not found
|
|
|
|
/api/memory/health:
|
|
get:
|
|
tags: [Memory]
|
|
summary: Memory store health check
|
|
description: >-
|
|
Round-trip create→list→delete to verify the store is alive.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Health result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
working:
|
|
type: boolean
|
|
latencyMs:
|
|
type: number
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/retrieve-preview:
|
|
post:
|
|
tags: [Memory]
|
|
summary: Dry-run memory retrieval (Playground)
|
|
description: >-
|
|
Simulates `retrieveMemories()` for a given query and returns the ranked
|
|
results with score, tier, and token count. Does NOT modify any memory.
|
|
Corresponds to `RetrievePreviewSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [query]
|
|
properties:
|
|
query:
|
|
type: string
|
|
minLength: 1
|
|
strategy:
|
|
type: string
|
|
enum: [exact, semantic, hybrid]
|
|
default: hybrid
|
|
maxTokens:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 16000
|
|
default: 2000
|
|
apiKeyId:
|
|
type: string
|
|
description: Optional — tests global pool when omitted
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 100
|
|
default: 20
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Preview results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
memories:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum: [factual, episodic, procedural, semantic]
|
|
key:
|
|
type: string
|
|
content:
|
|
type: string
|
|
score:
|
|
type: number
|
|
tokens:
|
|
type: integer
|
|
tier:
|
|
type: string
|
|
enum: [fts5, vector, hybrid-rrf, qdrant]
|
|
vecScore:
|
|
type: number
|
|
nullable: true
|
|
ftsScore:
|
|
type: number
|
|
nullable: true
|
|
resolution:
|
|
type: object
|
|
properties:
|
|
embeddingSource:
|
|
type: string
|
|
enum: [remote, static, transformers]
|
|
nullable: true
|
|
embeddingModel:
|
|
type: string
|
|
nullable: true
|
|
vectorStore:
|
|
type: string
|
|
enum: [sqlite-vec, qdrant, none]
|
|
strategyUsed:
|
|
type: string
|
|
enum: [exact, semantic, hybrid]
|
|
rerankApplied:
|
|
type: boolean
|
|
fallbackReason:
|
|
type: string
|
|
nullable: true
|
|
totalTokensUsed:
|
|
type: integer
|
|
budgetMaxTokens:
|
|
type: integer
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/embedding-providers:
|
|
get:
|
|
tags: [Memory]
|
|
summary: List embedding providers
|
|
description: >-
|
|
Returns all providers that have embedding-capable models, indicating
|
|
which have an active API key configured.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Provider list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
providers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
provider:
|
|
type: string
|
|
hasKey:
|
|
type: boolean
|
|
models:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: "Format: provider/model"
|
|
name:
|
|
type: string
|
|
dimensions:
|
|
type: integer
|
|
nullable: true
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/engine-status:
|
|
get:
|
|
tags: [Memory]
|
|
summary: Memory engine status
|
|
description: >-
|
|
Returns the full engine status including keyword tier availability,
|
|
embedding resolution, vector store statistics (sqlite-vec), Qdrant
|
|
health, and rerank configuration. Corresponds to `MemoryEngineStatusSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Engine status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
keyword:
|
|
type: object
|
|
properties:
|
|
available:
|
|
type: boolean
|
|
backend:
|
|
type: string
|
|
enum: [FTS5]
|
|
embedding:
|
|
type: object
|
|
properties:
|
|
source:
|
|
type: string
|
|
enum: [remote, static, transformers]
|
|
nullable: true
|
|
model:
|
|
type: string
|
|
nullable: true
|
|
dimensions:
|
|
type: integer
|
|
nullable: true
|
|
available:
|
|
type: boolean
|
|
reason:
|
|
type: string
|
|
cacheStats:
|
|
type: object
|
|
properties:
|
|
hits:
|
|
type: integer
|
|
misses:
|
|
type: integer
|
|
size:
|
|
type: integer
|
|
vectorStore:
|
|
type: object
|
|
properties:
|
|
backend:
|
|
type: string
|
|
enum: [sqlite-vec, qdrant, none]
|
|
available:
|
|
type: boolean
|
|
rowCount:
|
|
type: integer
|
|
needsReindex:
|
|
type: integer
|
|
reason:
|
|
type: string
|
|
qdrant:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
healthy:
|
|
type: boolean
|
|
nullable: true
|
|
latencyMs:
|
|
type: number
|
|
nullable: true
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
rerank:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
provider:
|
|
type: string
|
|
nullable: true
|
|
model:
|
|
type: string
|
|
nullable: true
|
|
available:
|
|
type: boolean
|
|
reason:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/summarize:
|
|
post:
|
|
tags: [Memory]
|
|
summary: Compact old memories
|
|
description: >-
|
|
Manually triggers memory compaction for memories older than
|
|
`olderThanDays`. Use `dryRun: true` to preview candidates.
|
|
Corresponds to `MemorySummarizeSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
olderThanDays:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 365
|
|
default: 30
|
|
apiKeyId:
|
|
type: string
|
|
description: Optional — compacts all keys when omitted
|
|
dryRun:
|
|
type: boolean
|
|
default: false
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Summarization result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
candidates:
|
|
type: integer
|
|
tokensSaved:
|
|
type: integer
|
|
dryRun:
|
|
type: boolean
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/memory/reindex:
|
|
post:
|
|
tags: [Memory]
|
|
summary: Trigger vector reindex
|
|
description: >-
|
|
Starts background reindexing of memories with `needs_reindex = 1`.
|
|
Use `force: true` to regenerate ALL vectors regardless of index status.
|
|
Corresponds to `MemoryReindexSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
force:
|
|
type: boolean
|
|
default: false
|
|
description: >-
|
|
When true, marks all memories needs_reindex=1 before running.
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Reindex started
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
started:
|
|
type: boolean
|
|
pending:
|
|
type: integer
|
|
description: Memories still pending after this batch
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/settings/memory:
|
|
get:
|
|
tags: [Memory, Settings]
|
|
summary: Get memory settings
|
|
description: >-
|
|
Returns the extended memory settings including 7 new fields added in
|
|
plan 21 (embeddingSource, embeddingProviderModel, transformersEnabled,
|
|
staticEnabled, rerankEnabled, rerankProviderModel, vectorStore).
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Extended memory settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemorySettingsExtended"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
put:
|
|
tags: [Memory, Settings]
|
|
summary: Update memory settings
|
|
description: >-
|
|
Update any subset of the extended memory settings.
|
|
All fields are optional; only provided fields are updated.
|
|
Schema: `MemorySettingsExtendedSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemorySettingsExtended"
|
|
responses:
|
|
"200":
|
|
description: Updated memory settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/MemorySettingsExtended"
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/settings/qdrant:
|
|
get:
|
|
tags: [Memory, Settings]
|
|
summary: Get Qdrant settings
|
|
description: >-
|
|
Returns current Qdrant configuration. The `apiKey` field is never
|
|
returned raw — use `hasApiKey` / `apiKeyMasked` instead.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Qdrant settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/QdrantSettings"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
put:
|
|
tags: [Memory, Settings]
|
|
summary: Update Qdrant settings
|
|
description: >-
|
|
Update Qdrant configuration. Pass `apiKey: ""` to remove the stored
|
|
key. Schema: `QdrantSettingsUpdateSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
host:
|
|
type: string
|
|
port:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 65535
|
|
collection:
|
|
type: string
|
|
minLength: 1
|
|
embeddingModel:
|
|
type: string
|
|
minLength: 1
|
|
apiKey:
|
|
type: string
|
|
description: Empty string removes the key
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Updated Qdrant settings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/QdrantSettings"
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/settings/qdrant/health:
|
|
get:
|
|
tags: [Memory]
|
|
summary: Qdrant health probe
|
|
description: >-
|
|
Performs a liveness check against the configured Qdrant instance.
|
|
Returns latency and any connection error (sanitized — no stack traces).
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Health result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/QdrantHealthResult"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/api/settings/qdrant/search:
|
|
post:
|
|
tags: [Memory]
|
|
summary: Qdrant semantic search test
|
|
description: >-
|
|
Performs a test semantic search against the Qdrant collection.
|
|
Useful for validating that the integration works end-to-end.
|
|
Schema: `QdrantSearchSchema`.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [query]
|
|
properties:
|
|
query:
|
|
type: string
|
|
minLength: 1
|
|
topK:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 50
|
|
default: 5
|
|
additionalProperties: false
|
|
responses:
|
|
"200":
|
|
description: Search results
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
results:
|
|
type: array
|
|
items:
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"503":
|
|
description: Qdrant unavailable (structured error, no stack trace)
|
|
|
|
/api/settings/qdrant/cleanup:
|
|
post:
|
|
tags: [Memory]
|
|
summary: Clean up expired Qdrant points
|
|
description: >-
|
|
Removes Qdrant points for memories that have expired or exceeded
|
|
the configured retention window.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Cleanup result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
deleted:
|
|
type: integer
|
|
checked:
|
|
type: integer
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"503":
|
|
description: Qdrant unavailable (structured error, no stack trace)
|
|
|
|
/api/settings/qdrant/embedding-models:
|
|
get:
|
|
tags: [Memory]
|
|
summary: List Qdrant embedding models
|
|
description: Returns the list of embedding models available for use with Qdrant.
|
|
security:
|
|
- ManagementSessionAuth: []
|
|
responses:
|
|
"200":
|
|
description: Embedding models list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
models:
|
|
type: array
|
|
items:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
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
|
|
|
|
# ─── Memory Engine schemas (plan 21 — v3.8.6) ─────────────────
|
|
|
|
MemoryEntry:
|
|
type: object
|
|
description: A single persisted memory entry
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: UUID
|
|
apiKeyId:
|
|
type: string
|
|
sessionId:
|
|
type: string
|
|
nullable: true
|
|
type:
|
|
type: string
|
|
enum: [factual, episodic, procedural, semantic]
|
|
key:
|
|
type: string
|
|
description: Stable upsert key (e.g. preference:i_prefer_python)
|
|
content:
|
|
type: string
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
updatedAt:
|
|
type: string
|
|
format: date-time
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
needsReindex:
|
|
type: integer
|
|
description: 1 if the vector for this memory is stale or missing
|
|
|
|
MemorySettingsExtended:
|
|
type: object
|
|
description: >-
|
|
Extended memory settings including 7 new fields from plan 21.
|
|
All fields are optional for PUT (patch semantics).
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
maxTokens:
|
|
type: integer
|
|
minimum: 0
|
|
maximum: 16000
|
|
retentionDays:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 365
|
|
strategy:
|
|
type: string
|
|
enum: [recent, semantic, hybrid]
|
|
skillsEnabled:
|
|
type: boolean
|
|
embeddingSource:
|
|
type: string
|
|
enum: [remote, static, transformers, auto]
|
|
description: >-
|
|
Which embedding source to use. "auto" = remote > static > transformers.
|
|
embeddingProviderModel:
|
|
type: string
|
|
nullable: true
|
|
description: >-
|
|
Embedding provider/model in "provider/model" format (e.g. openai/text-embedding-3-small).
|
|
transformersEnabled:
|
|
type: boolean
|
|
description: Opt-in for Transformers.js local MiniLM model (~400MB RAM)
|
|
staticEnabled:
|
|
type: boolean
|
|
description: Opt-in for static potion-base-8M local model
|
|
rerankEnabled:
|
|
type: boolean
|
|
description: Enable reranking step (+200-500ms/req)
|
|
rerankProviderModel:
|
|
type: string
|
|
nullable: true
|
|
description: Rerank provider/model in "provider/model" format
|
|
vectorStore:
|
|
type: string
|
|
enum: [sqlite-vec, qdrant, auto]
|
|
description: Which vector backend to use
|
|
|
|
QdrantSettings:
|
|
type: object
|
|
description: Qdrant vector database configuration (read shape — no raw apiKey)
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
host:
|
|
type: string
|
|
port:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 65535
|
|
collection:
|
|
type: string
|
|
embeddingModel:
|
|
type: string
|
|
hasApiKey:
|
|
type: boolean
|
|
apiKeyMasked:
|
|
type: string
|
|
nullable: true
|
|
description: First 4 chars of the configured API key, or null
|
|
|
|
QdrantHealthResult:
|
|
type: object
|
|
description: Result of a Qdrant liveness probe
|
|
properties:
|
|
ok:
|
|
type: boolean
|
|
latencyMs:
|
|
type: number
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
description: Sanitized error message (no stack traces)
|