Send Message

POST

api

threads

{threadId}

messages

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
      }
    ]
  }'

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();

{
  "success": true,
  "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
}

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

This endpoint queues the message and returns immediately. To receive the agent’s response in real-time, use the WebSocket stream.

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.

string

required

The unique thread identifier (UUID)

string

required

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

string

required

The message content

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.

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.

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.

string

Optional user identifier for tracking

boolean

required

Whether the message was successfully queued

string

required

The unique identifier for the created message

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
      }
    ]
  }'

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();

{
  "success": true,
  "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
}

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
      }
    ]
  }'

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();

{
  "success": true,
  "messageId": "msg_550e8400-e29b-41d4-a716-446655440000"
}

Threads

Messages

File System

Define Utilities

WebSocket