Send a message
POST /v1/sessions/{session_id}/messages- Permission
write:sessions- Tokens
- API key, CLI user token, Session token
Send a follow-up to a conversation. The response carries the message and the turn that answers it; a message sent while a turn runs is answered after it. Reuse an idempotency key when retrying the same message.
Path parameters
Request
Optional retry-safety key, unique per (session, key): a retry with the same key returns the original message , no duplicate message, no double turn, no double spend. The SDK auto-generates one per send.
Images attached to the message, base64 inline. Requires the model's images capability, which is not currently certified. Each becomes an `[Image #N]` placeholder in the stored body and an image block on the next turn. Up to 10, 5 MiB each; PNG, JPEG, GIF, or WebP.
The message text. May be empty when `images` is not.
Response
The message.
The turn that will answer the message. Wait on it: poll GET /v1/sessions/{id}/turns/{turn_id} or watch the stream's session frames until its status is final.