API Reference
API Overview & Errors
Base URLs, request headers, error structures, and retry semantics.
The Omni Developer API is exposed globally via high-performance edge infrastructure.
Base URL
https://edge.omnistatic.comAll developer API requests, agent sessions, and telemetry queries should be directed to this canonical base URL.
Required Request Headers
| Header | Value / Format | Required |
|---|---|---|
Authorization | Bearer omni_sk_live_... | Yes (all non-health endpoints) |
Content-Type | application/json | Yes (for POST / PUT / PATCH) |
X-Omni-Workspace | <workspaceId> | Optional (scopes chat/context to a workspace) |
Error Envelope
All failed requests return standard JSON error structures:
{
"error": {
"code": "unauthorized | forbidden | not_found | rate_limited | quota_exceeded | error",
"message": "Human-readable description of the error."
}
}HTTP Status Codes & Retry Guidelines
| HTTP Code | Error Code | Retry Policy |
|---|---|---|
400 | error / invalid_request | Do not retry. Fix the request payload or query parameters. |
401 | unauthorized | Do not retry. Verify your omni_sk_live_* API key or generate a new one. |
403 | forbidden | Do not retry. Verify that your API key has been granted the required scope. |
404 | not_found | Do not retry. The requested workspace, document, or memory does not exist. |
429 | rate_limited | Retry with exponential backoff. Respect the Retry-After header value. |
429 | quota_exceeded | Do not retry immediately. Account monthly token limit or credit limit reached. |
500 / 502 / 503 | error | Retry with exponential backoff (max 3 retries). |