Sessions

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

idstringrequired
{
"idempotency_key": str,
"message": str
}

Request

idempotency_keystring

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.

imagesarray<ImageAttachment>

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.

messagestringrequired

The message text. May be empty when `images` is not.

Response

messageSessionMessagerequired

The message. It is answered once the session's status is `idle` or `closed`; its `message_ended` record says how.

On this page

No Headings
Schedule a demo