---
title: "Send Session Message"
method: POST
path: "/v1/sessions/{id}/messages"
tags: ["v1"]
---

# Send Session Message

`POST /v1/sessions/{id}/messages`

## Request

- Base URL: `https://api.ellipsis.dev`
- URL: `https://api.ellipsis.dev/v1/sessions/{id}/messages`
- Auth: HTTP bearer

Send a message to a session.

409 for mention, non-interactive, closed, archived, and
out-of-budget sessions. Returns the created message; a retried send with the
same idempotency_key returns the original one. The message is
answered once the session's status is `idle` or `closed`.

## Path parameters

- `id` string, required

## Headers

- `user-agent` string, nullable

## Request body

- SendSessionMessageRequest: A human message posted into a durable session's conversation. Delivered to the live agent at the next turn boundary, or starts an agent for it when none is warm.
  - `idempotency_key` string, nullable: 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` 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.
    - `data` string, required: The raw image bytes, base64-encoded. 5 MiB cap.
    - `media_type` 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp', required: The image's MIME type: image/png, image/jpeg, image/gif, or image/webp. The bytes must match.
  - `message` string, required: The message text. May be empty when `images` is not.

## Response `200`

Successful Response

- SessionMessageResponse: One message sent to a session.
  - `message` SessionMessage, required: One message sent to a session.
    - `author` string, nullable: Display attribution of the message's sender.
    - `body` string, required: The message text, with one `[Image #N]` placeholder per attached image.
    - `created_at` string, date-time, required: When the message was received.
    - `id` string, required: Unique identifier of the message.
    - `images` SessionMessageImage[]: Images attached to the message, metadata only: index, media type, size. The bytes go to the model, never over the stream.
      - `id` string, nullable: The image's ID. `GET /v1/sessions/{session_id}/images/{id}` returns its bytes. Null when the image can't be fetched.
      - `index` integer, required: 1-based position: the N in `[Image #N]`.
      - `media_type` string, required: The image's MIME type.
      - `size_bytes` integer, required: Size of the decoded image, in bytes.
    - `index` integer, required: Position in the session, starting at 0.
    - `session_id` string, required: Identifier of the session the message belongs to.

## Other responses

- `400`: The message is empty, an image is invalid or over the limit, or the session's resolved combination is not supported. Unsupported combinations use code unsupported_session_combination.
- `401`: The bearer token is missing, invalid, or revoked.
- `403`: The credential may not perform this action, or the account is blocked.
- `404`: No such session in your account.
- `409`: The session cannot be messaged: it is closed, archived, non-interactive, or steered from its triggering surface (mention).
- `422`: Validation Error

---

[API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)