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.

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)

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.

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