Send a follow-up

POST/o/{org}/p/{project}/sessions/{session}/messages
View .md

Delivers a message to the session's agent. A parked resumable sandbox is woken first. When a turn is still running, the message is queued and delivered when the turn ends: the answer is then 202 with its place in the queue. Ephemeral sessions take no queued messages.

Authenticate with an org API key or a signed-in session.

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

projectstringrequired

A Project's handle (name) or id, resolved inside {org} — OR the reserved sentinel _ meaning "no Project" (a direct-repo / repo-less dispatch on POST; "no Project constraint, resolve by session id alone" everywhere else). A real handle that doesn't match the session's actual Project is 404.

sessionstringrequired

The session's full id (execution_id).

Request body

contentstringrequired

The message. At most 256 KiB.

Responses

200Delivered to the agent.
okbooleanrequired
statusstringrequired
202Queued behind the running turn.
okbooleanrequired
statusstringrequired
message_idstringrequired
Format uuid
positionintegerrequired

1-based place in the queue.

min 1
400No content, or content over its size limit (CONTENT_TOO_LARGE).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
402The plan does not cover more usage (same codes as starting a session).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one that exists in an org the caller cannot see.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
409The session cannot take a message: it is closed (TASK_TERMINAL), not started yet, ephemeral with a turn running (PERSISTENCE_MODE_CONFLICT), or its run cannot be continued (CONTINUATION_UNSUPPORTED).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The queue already holds 20 messages (QUEUE_FULL).
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional