Skip to main content
POST
Send a message

Authorizations

Authorization
string
header
required

Access token from POST /management/v1/auth/token (publishable-key exchange) or a login session. Publishable-key tokens are agent-scoped and serve the messaging surface; login tokens also serve management.

Body

application/json

Send a message to your agent — the agent is identified by your access token. thread_id is optional: present -> append to that thread; absent -> a new thread is created automatically and its id returned.

text
string
required
user_id
string
required
thread_id
string | null
Pattern: ^[0-9a-fA-F]{24}$|^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
image_url
string | null

Signed image URL for vision input.

agent_variables
Agent Variables · object

Per-message values for the agent's configured context variables.

runtime_version
string | null

Optional runtime build pin (e.g. '0.5.4') for agents on the runtime-v2 engine. Has no effect on which engine serves the agent; omit to use the current default runtime.

Response

Successful Response

Send/rerun reply plus the resolved thread id — the one the interaction landed on (newly created when the request omitted thread_id).

thread_id
string
required

Thread the interaction belongs to

message
Message · object
required

One message in a thread transcript.