Send a message
POST /v1/sessions/{id}/messages- Permission
write:sessions- Tokens
- API key, CLI user token, Session token
Send a follow-up to a session. The response carries the message. It is answered once the session is idle or closed, and its message_ended record says how. Reuse an idempotency key when retrying the same message.
Path parameters
Request
Optional retry safety key, unique per session. A retry with the same key returns the original message, with no second message, turn, or spend. The SDKs make a key for each call that sets none, so their own retries never send a message twice.
Images attached to the message, base64 inline. Requires the model's `images` capability, listed by `/v1/account/models`. 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. It is answered once the session's status is `idle` or `closed`; its `message_ended` record says how.