Sessions

Send a message

Send a follow-up to a conversation.

MethodPathRequired permissions
POST/v1/sessions/{session_id}/messages
write:sessions
Token access
API key
Supported.
CLI user token
Supported.
Sandbox token
Requires the ellipsis:api scope and the required grants in the token's permissions.ellipsis configuration.

Higher permission levels include lower levels: read < write < delete.

Grant match patterns can further restrict access to individual resources.

Messages received during a turn wait for the next turn. Reuse an idempotency key when retrying the same message.

Path parameters

session_idstringrequired
curl -X POST "https://api.ellipsis.dev/v1/sessions/{session_id}/messages" \
  -H "Authorization: Bearer $ELLIPSIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Add a regression test.",
  "idempotency_key": "add-test"
}'

Request

Example request body
{
"message": "Add a regression test.",
"idempotency_key": "add-test"
}

Body parameters

idempotency_keystring

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.

imagesarray<ImageAttachment>

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.

messagestringrequired

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

Response

Example response, 200
{
}

On this page

No Headings
Schedule a demo