> ## Documentation Index
> Fetch the complete documentation index at: https://docs.standardagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Message

Sends a message to a thread and triggers an agent response.

> [!NOTE]
>
> This endpoint queues the message and returns immediately. To receive the agent's response in real-time, use the [WebSocket stream](https://docs.standardagents.ai/api-reference/websocket/stream.md).

> [!NOTE]
>
> A message sent while the thread is running joins that run. The run adds it to the conversation before its next model request, after the results of the step in progress, and takes no extra turn for it. Several messages sent during a run reach the model in the order they were sent. A message sent to an idle thread starts a run.

**threadId** `string` *required*

The unique thread identifier (UUID)

**role** `string` *required*

Message role: `"user"`, `"system"`, or `"assistant"`

**content** `string` *required*

The message content

**attachments** `array`

Array of file attachments. Each attachment object:

* `name` (string, required): Filename
* `mimeType` (string, required): MIME type (e.g., `image/jpeg`)
* `data` (string, required): Base64-encoded file data
* `width` (number): Image width in pixels (optional, returned in response)
* `height` (number): Image height in pixels (optional, returned in response)

The message is accepted whole or not at all. If any attachment's `data` is not valid base64, the request returns `400`: no file and no message is stored, and no run starts. If an attachment cannot be stored, the request returns a `5xx` status and the message is not queued.

All images are automatically processed: resized to fit under 1.5MB and converted to JPEG. The processed `width` and `height` are stored and returned in message attachments.

Each stored attachment is returned on the message as a reference whose `size` is the number of bytes in the stored file.

> [!NOTE]
>
> A thread that is being deleted refuses the message with `423`, and a deleted thread returns `404`.
>
> A terminated thread refuses the message with `423` and the error body `{ "error": { "code", "message" }, "requestId" }`. No message is stored and no run starts. Non-execution routes, including thread and message reads and updates, files, stop, the stream, and thread deletion, remain available. The debug continuation endpoint also refuses execution on a terminated thread.

> [!NOTE]
>
> This endpoint queues a message only. It does not seed `ThreadState.arguments` or `state.context`; invocation and subagent creation arguments are runtime execution data, not message body fields.

**userId** `string`

Optional user identifier for tracking

**success** `boolean` *required*

Whether the message was successfully queued

**messageId** `string` *required*

The unique identifier for the created message

```bash cURL theme={null}
curl -X POST https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages \
  -H "Content-Type: application/json" \
  -d '{
    "role": "user",
    "content": "Here is a photo of the issue",
    "attachments": [
      {
        "name": "photo.jpg",
        "mimeType": "image/jpeg",
        "data": "/9j/4AAQSkZJRg...",
        "width": 4000,
        "height": 3000
      }
    ]
  }'
```

```typescript JavaScript theme={null}
const response = await fetch(
  'https://your-worker.workers.dev/api/threads/550e8400-e29b-41d4-a716-446655440000/messages',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      role: 'user',
      content: 'Here is a photo of the issue',
      attachments: [{
        name: 'photo.jpg',
        mimeType: 'image/jpeg',
        data: base64EncodedImage,
        width: 4000,
        height: 3000
      }]
    })
  }
);
const result = await response.json();
```

```json 200 theme={null}
{
  "success": true,
  "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.