Gateway API

The gateway is OpenAI-compatible. Point any OpenAI SDK at {ZEAGATE_PUBLIC_URL}/v1 with a zea- virtual key.

Method	Path	Auth	Purpose
POST	/v1/chat/completions	Bearer	Chat (streaming and non-streaming)
POST	/chat/completions	Bearer	Alias
POST	/v1/embeddings	Bearer	Embeddings (OpenAI / Azure only)
POST	/embeddings	Bearer	Alias
POST	/v1/responses	Bearer	OpenAI Responses API (non-streaming)
POST	/responses	Bearer	Alias
POST	/v1/audio/transcriptions	Bearer	Speech-to-text (OpenAI / Azure)
POST	/audio/transcriptions	Bearer	Alias
POST	/v1/audio/speech	Bearer	Text-to-speech (OpenAI / Azure)
POST	/audio/speech	Bearer	Alias
WebSocket	wss://…/v1/realtime?model=<group>	Bearer (upgrade)	Realtime voice (see Realtime)
GET	/realtime	Bearer (upgrade)	Alias (same WebSocket endpoint)
GET	/v1/models	Bearer	Model groups the key may use
GET	/health	None	DB connectivity
GET	/health/liveliness	None	Process up
GET	/health/readiness	None	DB + Redis

See Audio (STT & TTS) and Realtime (WebSocket). Cache invalidation is Redis pub/sub, not HTTP.

OpenAPI

The HTTP surface is described in OpenAPI 3.1:

GET /openapi.json

No authentication required. The document is versioned in the repository as openapi/zeallm-gateway-v1.yaml (generated JSON is embedded in the gateway). Use it with Postman, code generators, or the portal API reference page (/developers/api), which also downloads it.

Not in OpenAPI: Realtime WebSocket event protocol — see Realtime.

Key-scoped models: GET /v1/models with your zea- key lists which model groups you may call (separate from the global OpenAPI contract).

Request lifecycle (chat)

1. Auth — hash lookup; blocked/expired keys rejected
2. Model access — key allowlist
3. Budgets — every level must pass
4. Rate limits — RPM/TPM for key, team, application, customer
5. Pre-request guardrails
6. Routing — weighted pick, retries, fallbacks
7. Stream or return the provider response
8. Post-response guardrails
9. Async spend log

Error envelope

Gateway-generated errors:

{
  "error": {
    "message": "human-readable message",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Upstream provider errors are passed through with the upstream status and body.

See Error codes, headers and SDK snippets.