API conventions
Shared rules for base URL, auth, errors, and pagination across the REST API.
Base URL
All paths in this reference are relative to your deployment’s API root, including any /v1 prefix (for example https://api.example.com/v1).
Authentication
Send Authorization: Bearer <API_KEY> on every request. See Authentication.
Content type
Use Content-Type: application/json for JSON bodies. Multipart endpoints (for example audio upload) use multipart/form-data as noted.
Errors
Errors return JSON with at least error metadata compatible with common OpenAI shapes when upstream provides it. Typical statuses:
| Code | Meaning |
|---|---|
400 | Validation / bad parameters |
401 | Auth failed |
403 | Forbidden for this key/org |
429 | Rate limited |
500 | Server error — retry with backoff |
Idempotency
User-retryable financial or sensitive operations may require idempotency keys per product policy. Chat and audio calls are not automatically idempotent—deduplicate in your client when needed.
Choose an endpoint below for request and response bodies.