Skip to main content
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
      }
    ]
  }'

{
  "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.
​
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)
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.
​
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
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
      }
    ]
  }'

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