POST /api/v1/completions. Omit chatId to create a chat and queue the turn. Pass chatId to continue an existing chat. POST /api/v1/chats is optional when you want an empty chat or a title first.
Send text and an image in one request. Use multipart/form-data with text + file. JSON is for text, or text plus a public image_urls if the file is already hosted.
Request
string
required
The message to send, up to 8192 characters.
file
Multipart. Upload an image (or video/audio) in the same request as
text. Repeat file or use files for more than one. See Upload files.string[]
JSON only. Public
http(s) URLs when the file is already hosted.string[]
IDs from
POST /uploads or files already in the product.boolean
When true, the agent pauses for plan approval before tools.
string
Omit it to send a first message (a chat is created). Pass it to continue an existing chat.
Response
POST /completions returns 202.
string
string
string
Poll this on the runs route.
string
Orchestrator id. Nullable if dispatch has not attached yet.
string
Always
queued at admission. Later states are on the run snapshot.Routes
GET supports limit and cursor. Each message includes contentBlocks and attachments. If the message has files, attachments[].id is the attachment id (uploads on the user turn, generated images on the assistant turn).
One active run per chat. A second send before the run reaches
COMPLETE, FAILED, or CANCELLED returns 409 RUN_ACTIVE.