API overview¶
The gateway exposes four HTTP routes. Three are client-facing; one
(/metrics) is for monitoring.
| Method | Path | Purpose |
|---|---|---|
GET |
/healthz |
Liveness probe. Always returns 200. |
GET |
/metrics |
Prometheus metrics. |
POST |
/v1/chat/completions |
OpenAI-compatible chat completions. |
POST |
/v1/route/decision |
Dry-run a routing decision (no upstream call). |
Production base URL:
The OpenAI-compatible surface is under /v1. There is no
/v1/models endpoint in v1.0.0; clients should pass an alias
directly. (An upstream /v1/models call against OpenRouter would
list every model on the platform, which is not what the gateway
exposes.)
Stable vs unstable surface¶
Everything documented here is part of the v1.0.0 freeze:
- The endpoint paths and HTTP methods.
- The request and response shapes.
- The status codes returned for each kind of failure.
- The four aliases and their mapping to real OpenRouter IDs.
Anything not listed here (custom headers beyond the documented set, additional metadata keys, undocumented response fields) is internal and may change without notice. The freeze ID is checked at startup and a mismatch prevents the gateway from booting.
Versioning¶
The gateway does not embed an HTTP version indicator. The release
that produced this surface is v1.0.0. Future breaking changes will
be issued as a new major release with a new freeze ID and a
documented migration path. Bug fixes that preserve the wire format
do not bump the major version.
Authentication¶
Every endpoint except /healthz requires a gateway API key in
Authorization: Bearer <key>. See
User guide → Authentication.
CORS¶
The gateway does not implement CORS. Browsers must call the gateway through their own backend. The supported client tools (Aider, Cline, Roo-Code, OpenAI SDK) all run server-side or in Node, so this is not a limitation in practice.
Rate limits¶
The gateway itself does not enforce rate limits. OpenRouter rate limits apply on the upstream and are propagated as 429 responses after the gateway's internal retry loop exhausts. See User guide → Errors.
Timeouts¶
| Phase | Limit |
|---|---|
| nginx → gateway | proxy_read_timeout 300s |
| gateway → OpenRouter | 60s per attempt, 3 attempts with backoff |
| Pydantic validation | synchronous |
| Routing decision (in-process) | < 1 ms typical |