POST /v1/sessions/{session_id}/messages - Create message (user message triggers workflow)

POST

/v1/sessions/{session_id}/messages

• Production API

Parameters

Path Parameters

session_id

required

string

Session ID (prefixed, e.g., sess_…)

Request Body ^required

Request to create a message

object

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

message

required

The message to create

object

content

required

Array of content parts (text and image only)

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

role

Message role (always “user” for API-created messages)

string

Allowed values: system user agent tool_result

metadata

Request-level metadata

object | null

tags

Tags for the message

array | null

Responses

201

Message created successfully

A message in the conversation

object

content

required

Message content as array of content parts (text, images, tool calls, tool results)

Array

One of:

unknown

Text content

object

text

required

string

type

required

string

Allowed values: text

unknown

Image content (base64 or URL)

object

base64

string | null

media_type

string | null

url

string | null

type

required

string

Allowed values: image

unknown

Image file content (reference to uploaded image by ID)

object

filename

Original filename (for display)

string | null

image_id

required

ID of the uploaded image (format: img_{32-hex})

string

Example

img_01933b5a00007000800000000000001

type

required

string

Allowed values: image_file

unknown

Tool call content (assistant requesting tool execution)

object

arguments

required

id

required

string

name

required

string

type

required

string

Allowed values: tool_call

unknown

Tool result content (result of tool execution)

object

error

string | null

result

tool_call_id

required

ID of the tool call this result corresponds to

string

type

required

string

Allowed values: tool_result

controls

One of:

null

null

object

Runtime controls (model, reasoning, etc.)

object

model_id

Model ID to use for this message (format: model_{32-hex}). Overrides session and agent model settings.

string | null

Example

model_01933b5a00007000800000000000001

reasoning

One of:

null

null

object

Reasoning configuration

object

effort

Effort level for reasoning (low, medium, high)

string | null

created_at

required

Timestamp when the message was created

string format: date-time

id

required

Unique message ID (format: message_{32-hex})

string

Example

message_01933b5a00007000800000000000001

metadata

Message-level metadata

object | null

role

required

Message role

string

Allowed values: system user agent tool_result

thinking

Thinking content from extended thinking models (Anthropic Claude) This is the model’s chain-of-thought reasoning before producing the response. Must be included in subsequent API calls when thinking is enabled.

string | null

thinking_signature

Cryptographic signature for thinking content (Anthropic Claude) Required when sending thinking back in subsequent API calls.

string | null

400

Invalid ID format

404

Session not found

500

Internal server error