POST/v1/chat/completions
OpenAI-compatible chat, blocking and streaming, with provider-specific parameter handling. Unsupported translated parameters return a clear error; validate your selected adapter.
One governed request path
An API you can inspect.
Authenticate at the self-hosted control plane, route model requests through a shared gateway, and evaluate the explicit MCP and A2A beta scope.
Updated · Public beta
Authenticate before inference
Send a gateway client key as Authorization: Bearer <OmniSwitch key>. Provider credentials remain upstream secrets. Local development uses http://localhost:8080/v1; terminate TLS before exposing a deployment.
A minimal chat requestShell
curl http://localhost:8080/v1/chat/completions \
-H "Authorization: Bearer $OMNISWITCH_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello"}]}'Model endpoints
POST
POST/v1/embeddings
OpenAI-compatible embeddings through providers that implement the endpoint. Input checks and provider fallback scope apply.
POST/v1/rerank
Rerank requests through providers that implement reranking. This is a documented request shape, not a blanket OpenAI API claim.
POST/v1/responses
A documented Responses subset. Tool-capable streaming translation is part of the unreleased v0.2.0 work; no stateful previous_response_id support.
POST/v1/messages
A documented Messages subset. Tool-use and streaming translation are part of the unreleased v0.2.0 work. Do not assume direct Anthropic SDK header compatibility.
GET/v1/models
Models registered by provider adapters and catalog aliases. Available models depend on your provider configuration.
OpenAI image generation, multipart audio transcription, and audio speech are planned for the v0.2.0 release with the OpenAI provider. Other providers are not implied to support them.
Read endpoint and parameter scopeMCP & A2A
/mcpBeta
HTTP-facing tool discovery and calls across configured HTTP/SSE and stdio targets, subject to gateway policy. MCP is off by default in the release-foundation evaluation path.
/.well-known/agent-card.jsonBeta
Public Agent Card discovery; model access is authenticated at /a2a.
SendMessage, SendMessageStream (SSE task events), GetTask, best-effort CancelTask; tasks in memory; no push notifications; no downstream agent proxy.
Inspect the A2A implementationGateway headers
| Header | Purpose |
|---|---|
Authorization | Bearer gateway API key when auth is enabled |
x-omniswitch-provider | Force a configured provider or alias |
x-omniswitch-config | Select a saved gateway config by name or ID |
x-omniswitch-model | Set the model for A2A messages; chat uses the JSON model field |
x-omniswitch-shadow-provider | Run a configured secondary provider asynchronously |
x-omniswitch-trace-id | Group calls into a request trace |
x-omniswitch-session-id | Group calls into an agent session |
x-omniswitch-workspace-id | Workspace context (subject to key scope) |
x-omniswitch-organization-id | Organization context (subject to key scope) |
x-omniswitch-tags | Request tags |
x-omniswitch-metadata | Request metadata |
x-omniswitch-user-id | Caller-supplied user context |
These are OmniSwitch headers, not aliases for competitor header conventions. Responses report x-omniswitch-cache: HIT or MISS. Cache isolation is configured with gateway.cache_scope, not a request header. Per-key scope is the safer default; global caching is appropriate only for tenant-independent public prompts.
Health & telemetry
| Endpoint | Scope |
|---|---|
/healthz | Public process health probe |
/readyz | Public readiness probe |
/metrics | Prometheus; authenticated unless explicitly configured public |
/api/* | Management routes are authenticated and role-scoped, except documented public health checks |
Output guardrail buffering can delay SSE delivery until the full response has been scanned. Benchmark results remain pending; no latency promise is made.