Send a message
Send a follow-up to a conversation.
| Method | Path | Required permissions |
|---|---|---|
| POST | /v1/sessions/{session_id}/messages | write:sessions |
- 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
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"
}'import os
from ellipsis import Ellipsis
from ellipsis import models
client = Ellipsis(api_key=os.environ["ELLIPSIS_API_TOKEN"])
request = models.SendSessionMessageRequest.model_validate(
{
"message": "Add a regression test.",
"idempotency_key": "add-test"
}
)
result = client.sessions.send_message(
"session_example",
request.message,
idempotency_key=request.idempotency_key,
)
print(result)import { Ellipsis } from '@ellipsis-dev/sdk';
const client = new Ellipsis({
apiKey: process.env.ELLIPSIS_API_TOKEN!,
});
const request: Parameters<typeof client.sessions.sendMessage>[1] = {
"message": "Add a regression test.",
"idempotency_key": "add-test"
};
const result = await client.sessions.sendMessage("session_example", request);
console.log(result);Request
Body parameters
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.