HTTP endpoints
The data-plane and admin-plane HTTP routes Orca AI Gateway serves, with methods, paths, and error codes.
The gateway binds two listeners. The data plane carries client traffic and runs the full governance pipeline. The admin plane carries health, metrics, and configuration, and runs no pipeline at all.
Data plane
Default 0.0.0.0:8080.
| Method | Path | Notes |
|---|---|---|
POST | /v1/chat/completions | OpenAI chat shape, with streaming. |
POST | /v1/embeddings | OpenAI embeddings shape. |
POST | /v1/messages | Anthropic Messages shape, with streaming. |
POST | /v1/responses | Native OpenAI Responses JSON or streaming SSE. Requires an openai destination. |
POST | /v1/llm/v1/messages | Anthropic compatibility path for an Agent Engine LLM_GATEWAY_URL ending in /v1/llm. |
POST | /v1/llm/responses, /v1/llm/v1/responses | Responses compatibility paths for Agent Engine. |
POST | /v1/mcp | MCP JSON-RPC over HTTP. |
GET | /v1/mcp | MCP Streamable HTTP server-push channel. |
GET | /v1/mcp/sse | MCP over Server-Sent Events. |
POST / GET | /mcp | Deprecated aliases for /v1/mcp. |
POST | /v1/proxy/{provider}/* | Native API-key proxy for an explicitly configured provider, protocol, route, and allowed upstream path. |
GET | /v1/models | Registered stub. Returns an empty OpenAI-shaped list. |
POST /v1/agent/sessions and POST /v1/agent/sessions/{id}/steps are registered but return
501 not_implemented. Do not build against them.
Native Responses does not support content guardrail plugins or background requests. Its route must
target an OpenAI destination without model mapping or target parameter shaping. The native API-key
proxy requires one matching native_api_key destination and does not support retries, fallback,
load balancing, or content guardrails. See Destinations for
the required configuration.
Admin plane
Default 127.0.0.1:9099. Keep it off the network.
Health and metrics
| Method | Path | Notes |
|---|---|---|
GET | /healthz | Liveness. Returns 200 once the process is up. |
GET | /readyz | Process readiness. The CLI marks it ready after AppState construction. |
GET | /metrics | Prometheus exposition. |
Configuration
| Method | Path | Notes |
|---|---|---|
GET | /admin/v1/config | The full active configuration. |
POST | /admin/v1/config/validate | Structural and live validation of a supplied config. |
GET | /admin/v1/spend/usage | Query the deduplicated Postgres usage ledger. Accepts from, to, group_by, and dim.<name> filters. |
GET | /admin/v1/guardrails/effective?session_id=... | Return the effective policy bundle already cached for a verified session. Does not fetch or fabricate a partial identity. |
GET | /admin/v1/pricing/resolve?provider=...&model=... | Resolve a model through the active cost model. Optional destination selects a destination override. |
GET | /admin/v1/destinations | List destinations. |
PUT / DELETE | /admin/v1/destinations/{name} | Upsert or remove a destination. |
GET | /admin/v1/routes | List routes. |
PUT / DELETE | /admin/v1/routes/{name} | Upsert or remove a route. |
PUT / DELETE | /admin/v1/rate_limits/{name} | Upsert or remove a rate limit. |
PUT / DELETE | /admin/v1/vaults/{name} | Upsert or remove a vault. |
PUT / DELETE | /admin/v1/config/plugins/{name} | Upsert or remove a plugin instance. |
GET | /admin/v1/health/plugins | Plugin counts and status. |
Resource writes are PUT and DELETE; POST is reserved for config/validate and for WASM
plugin installation. Writes succeed only against a
Postgres-backed gateway - with a file-backed config the admin surface is read-only.
Plugin installation
| Method | Path | Notes |
|---|---|---|
GET | /admin/v1/plugins | List installed plugins. |
POST | /admin/v1/plugins | Install a WASM plugin. |
DELETE | /admin/v1/plugins/{name} | Uninstall a WASM plugin. |
The shipped binary does not start the WebAssembly host, so POST /admin/v1/plugins returns
503 wasm_plugins_disabled. WASM plugins cannot be installed.
Errors
Failures carry a machine-readable code. The ones you are most likely to see:
| Status | Code | Cause |
|---|---|---|
400 | guardrail_blocked_input, guardrail_blocked_output | A payload guardrail blocked the request or its response, or its backend failed under failure_mode: deny. |
403 | forbidden | An authorizer denied the request. |
403 | policy_guardrail_denied | A policy guardrail denied a model request. |
404 | no_route | No compatible destination exists for the request. |
429 | - | A rate or spend limit was exceeded. |
503 | usage_query_unavailable | No queryable Postgres usage sink is configured. |
503 | guardrails_unavailable | GET /admin/v1/guardrails/effective was called while policy guardrails are off. |
503 | pricing_unavailable | No cost model is configured. |
503 | wasm_plugins_disabled | WASM plugin installation attempted. |
501 | not_implemented | An agent-session endpoint was called. |
When every target in a fallback chain fails, the gateway maps the final provider failure to its gateway error response.