Skip to content
Sign inGet started

Copy page
View as MarkdownPlain text for this pageOpen in ChatGPTQuestions about this pageOpen in ClaudeQuestions about this page

Send Message

POST/api/threads/{threadId}/messages

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

threadIdstringrequired

The unique thread identifier (UUID)

rolestringrequired

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

contentstring

Message text. Provide non-whitespace content or at least one attachment.

attachmentsarray

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)
  • thumbnail (string): Optional base64-encoded thumbnail. Invalid base64 returns 400.

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.

Images larger than approximately 2 MiB or in formats other than JPEG and PNG are submitted for processing. Processing targets a 1.5 MiB JPEG. A processing failure preserves the original file. JPEG and PNG images below the threshold retain their input bytes. Processed dimensions are returned in the attachment reference.

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

silentbooleandefault: false

Set true to store the message as a silent message. A silent message is left out of message reads and stream frames unless the reader asks for silent messages (includeSilent), and it does not change the thread's list preview or recency. silent controls presentation only: the model receives the message, and it starts or joins a run like any other message. A value that is not a boolean returns 400.

status'queued'required

The message was accepted durably for delivery.

messageIdstringrequired

The unique identifier for the created message