API reference
Contract chính thức, base URL, endpoint và quy ước tương thích của Developer API.
Developer API v1 hiện ở giai đoạn Preview. Hai machine-readable contract dưới đây là nguồn chính thức cho request, response và event schema:
OpenAPI 3.1
REST, SSE, authentication và response schemas.
AsyncAPI 3.1
Voice WebSocket, client events và server events.
Environment
| Environment | Base URL | Trạng thái |
|---|---|---|
| Production | https://api.assistantcore.com | Preview |
Preview chưa có sandbox tách biệt. Dùng assistant và API key riêng cho staging; request staging vẫn có thể tạo dữ liệu thật và sử dụng credits.
Authentication
Mọi REST endpoint dùng Developer API key qua header:
Authorization: Bearer ac_<public-id>_<secret><checksum>API key xác định assistant và chỉ được phép gọi operation có scope tương ứng. Voice WebSocket không nhận API key; client gửi session token ngắn hạn trong event session.start.
Operations
| Method | Path | Scope | Thành công |
|---|---|---|---|
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 |
Xem Chat API và Voice API để có request, response và streaming examples. Xem Lỗi và giới hạn trước khi triển khai retry.
Compatibility trong Preview
- Thay đổi tương thích ngược có thể được thêm vào
/v1mà không đổi path. - Thay đổi phá vỡ contract sẽ được ghi trong changelog trước khi rollout khi có thể.
- Không phụ thuộc vào field hoặc event không xuất hiện trong OpenAPI/AsyncAPI.
- Client phải bỏ qua response field và event type chưa biết, trừ khi operation yêu cầu xử lý terminal event.
- Contract GA, thời gian deprecation và sunset policy sẽ được công bố trước khi Preview kết thúc.
Preview không phải cam kết tương thích GA. Pin code generation vào một bản contract đã kiểm thử và kiểm tra changelog trước khi cập nhật.