API reference

Using the unified API

One endpoint, OpenAI-compatible in shape. Point an existing client at it by changing the base URL and the key.

Endpoint

POST /api/v1/chat/completions
Authorization: Bearer omr_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Request

model and policy are optional. Omit both and the environment's default policy decides.

{
  "messages": [
    { "role": "system", "content": "You are a support assistant." },
    { "role": "user", "content": "Draft a reply to this complaint." }
  ],
  "max_tokens": 400,
  "temperature": 0.7,
  "policy": "Balanced production"
}

Response

Standard fields plus a namespaced omnirouter block that OpenAI-shaped clients ignore.

{
  "id": "ed190580-fd01-44a3-9e46-eb20fe7f435e",
  "object": "chat.completion",
  "model": "astra-fast",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 63,
    "total_tokens": 73
  },
  "omnirouter": {
    "correlation_id": "ed190580-…",
    "provider": "DEMO",
    "fallback_used": false,
    "attempts": 1,
    "estimated_cost": 0.000039,
    "latency_ms": 540,
    "policy": "Balanced production",
    "strategy": "BALANCED",
    "routing_reason": "Astra Fast scored highest against the
      configured scoring policy. 3 candidates were eligible."
  }
}

Response headers

Present on both success and failure, so a failed request is still traceable.

x-omnirouter-correlation-id: ed190580-fd01-44a3-9e46-eb20fe7f435e
x-omnirouter-fallback-used: false
x-omnirouter-attempts: 1
x-omnirouter-quota-warning: (only when a quota threshold is crossed)

Idempotency

Send an Idempotency-Key header to guarantee at-most-once execution per workspace. A replay returns 409 with the original correlation id.

Idempotency-Key: order-4821-summary

Errors

Provider error text is never forwarded — it can echo prompt content or internal endpoints.

API error codes
Code	HTTP	Meaning
invalid_api_key	401	Missing, unknown, revoked or expired key.
invalid_request	400	The body failed schema validation.
invalid_json	400	The body was not parseable JSON.
payload_too_large	413	The body exceeded the size limit.
unknown_policy	400	The named policy does not exist in this workspace.
idempotency_replay	409	This Idempotency-Key was already processed.
quota_exceeded	429	A configured workspace quota rejected the request.
rate_limit	429	Every eligible provider rate limited the request.
timeout	504	No provider responded within the configured timeout.
provider_unavailable	502	Every eligible provider was unavailable.
context_limit	400	The request exceeds every eligible model’s context window.