Overview
Connect your application to an assistant's chat, files, conversations, and voice.
The Developer API lets a backend call an assistant over REST, Server-Sent Events (SSE), and WebSocket. The API key identifies the assistant; your application supplies an external_user_id to isolate conversations and memory for each end user.
Developer API v1 is in Preview. The contract may change before the API reaches GA.
Quickstart
Create an API key and send your first chat request.
API keys and security
Scopes, billing, user data, and key management.
API reference
OpenAPI, AsyncAPI, operations, and compatibility policy.
Chat API
Chat, streaming, files, conversations, and feedback.
Voice API
Voice sessions, events, audio, and reconnection.
Recommended integration flow
- The client signs in to your application backend.
- Your backend maps the authenticated user to a stable
external_user_id. - Your backend calls the Developer API with an API key stored in a secret manager.
- Your backend returns JSON or forwards SSE to the client. For voice, it returns only the short-lived session details and
websocket_url.
Do not accept an arbitrary external_user_id from the client and pass it through to Assistant Core. Derive it from the authenticated user or session so one user cannot access another user's conversations.
Endpoints and scopes
| Endpoint | Scope | Purpose |
|---|---|---|
POST /v1/chat/responses | chat:write | Create a JSON response or SSE stream. |
GET /v1/responses/{id} | chat:write | Retrieve a finished response. |
POST /v1/files | files:write | Upload a file for an external user. |
GET /v1/conversations/{id} | conversations:read | Retrieve conversation metadata. |
GET /v1/conversations/{id}/messages | conversations:read | Read paginated message history. |
POST /v1/messages/{id}/feedback | feedback:write | Submit an up or down rating. |
POST /v1/voice/sessions | voice:connect | Create a short-lived token for the Voice WebSocket. |
DELETE /v1/users/{external_user_id} | users:delete | Erase an end user's data. |
Choose an integration
| Goal | Use |
|---|---|
| Add a ready-made chat interface to a website | Web Widget |
| Build a custom UI, workflow, or backend automation | Developer API |
| Build a voice client and manage audio yourself | Voice API |
| Use the ready-made chat and voice app on your domain | Web App |
An API key is a server-side secret. Never put it in a browser, mobile application, source code, URL, or logs. Browser voice receives only a short-lived, single-use session token.
Implementation path
- Start with a non-streaming chat request to verify the key, plan, and identity mapping.
- Use the API reference as the canonical source for schemas and code generation.
- Add SSE, file uploads, and conversation history after the basic flow works.
- Implement the Voice API only when the client can manage audio capture, codecs, and playback.
- Before production, apply the key management and retry and rate-limit guidance.