API reference
Canonical contracts, base URL, operations, and compatibility conventions for the Developer API.
Developer API v1 is currently in Preview. The machine-readable contracts below are authoritative for request, response, and event schemas:
OpenAPI 3.1
REST, SSE, authentication, and response schemas.
AsyncAPI 3.1
Voice WebSocket client and server events.
Environment
| Environment | Base URL | Status |
|---|---|---|
| Production | https://api.assistantcore.com | Preview |
Preview has no isolated sandbox. Use a separate assistant and API key for staging; staging requests can still create real data and consume credits.
Authentication
Every REST endpoint uses a Developer API key in the header:
Authorization: Bearer ac_<public-id>_<secret><checksum>The key identifies the assistant and can call only operations allowed by its scopes. The Voice WebSocket never receives the API key; the client sends a short-lived session token in the session.start event.
Operations
| Method | Path | Scope | Success |
|---|---|---|---|
POST | /v1/chat/responses | chat:write | 200 |
GET | /v1/responses/{response_id} | chat:write | 200 |
POST | /v1/files | files:write | 201 |
GET | /v1/conversations/{conversation_id} | conversations:read | 200 |
GET | /v1/conversations/{conversation_id}/messages | conversations:read | 200 |
POST | /v1/messages/{message_id}/feedback | feedback:write | 204 |
POST | /v1/voice/sessions | voice:connect | 201 |
DELETE | /v1/users/{external_user_id} | users:delete | 204 |
See Chat API and Voice API for request, response, and streaming examples. Read Errors and limits before implementing retries.
Preview compatibility
- Backwards-compatible additions may be made to
/v1without changing the path. - Breaking contract changes will be recorded in the changelog before rollout whenever possible.
- Do not depend on fields or events absent from the OpenAPI or AsyncAPI contract.
- Clients must ignore unknown response fields and event types unless an operation requires handling a terminal event.
- The GA contract, deprecation period, and sunset policy will be published before Preview ends.
Preview is not a GA compatibility commitment. Pin code generation to a tested contract revision and review the changelog before updating.