LLM APIs
Manage conversations, messages, tools and semantic memory through the native conversation API. Voice operations require separately enabled voice service, provider credentials and an available voice agent. See Voice availability. Native endpoints do not use the OpenAI wire protocol.
User-facing calls act for the authenticated beneficiary. A backend sk_… key uses an authorized X-On-Behalf-Of selection with users:impersonate; a client pk_… key accompanies that user’s JWT from the configured issuer. Never expose a secret key in a client. Raw identity headers and recipient IDs are not authentication. See Authentication.
Tenant context comes from the authenticated request. Client-supplied X-Tenant-Id, X-User-Id or X-Project-Id do not grant authority. The current public integration uses the default project. Do not rely on project headers for separate project, test/live or customer isolation on this API.
A successful HTTP request can accept work that is still running, queued, awaiting client tools or failed. Inspect the run status and correlate it to the accepted runId; idle conversation state alone is not a terminal receipt for that request. Unknown or absent status means an unknown outcome, not success or proven ongoing execution.
Related guides: Conversations, Agent tools, Memory, Streaming availability
JSON conventions
Requests accept snake_case or camelCase field names; responses use camelCase. Ordinary default-valued scalars and empty repeated fields can be omitted. Explicitly present optional scalars, map values and well-known JSON types follow their own presence rules: an explicit false, 0 or empty value is not universally equivalent to absence. Decode each field according to its schema. 64-bit integers use JSON strings; preserve their precision. Unknown request fields are generally discarded before validation, so a typo can silently change behavior. This is not a guarantee that arbitrary fields or future client contracts are supported. See API conventions.
Authentication
- API Key: apiKeyAuth
- API Key: onBehalfOf
- HTTP: Bearer Auth
Project/service API key. Use pk_… only with a verified end-user JWT; backend sk_… calls that require a user use authorized on-behalf-of context. Management operations can have different requirements; consult the operation and authentication guide.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-API-Key |
The end user this call acts for. Required with an sk_… key, because a secret
key identifies your tenant and not a user; omitting it returns
401 authenticated user_id is required. The key needs the users:impersonate
scope or the call fails with 403 insufficient_scope.
Security Scheme Type: | apiKey |
|---|---|
Header parameter name: | X-On-Behalf-Of |
The end user's own JWT, issued by the OIDC provider configured on the
publishable key. Required alongside a pk_… key, and supplies the user
identity in place of X-On-Behalf-Of.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |
Bearer format: | JWT |
📄️ Overview
Manage conversations, messages, tools and semantic memory through the native conversation API. Voice operations require separately enabled voice service, provider credentials and an available voice agent. See [Voice availability](/managed-agents/voice-media). Native endpoints do not use the OpenAI wire protocol.
📄️ Messages and runs
overview}
📄️ Context and compaction
overview}
🗃️ Endpoints
11 items
🗃️ Models
24 items
Document ID: DOC-MA-conversations-api-overview. Section identities and revisions.
| Section | Stable reference |
|---|---|
| Overview | DOC-MA-conversations-api-overview#overview |
| JSON conventions | DOC-MA-conversations-api-overview#json-conventions |
| Authentication | DOC-MA-conversations-api-overview#authentication |