Threads API

Send a message

Send another message to a thread's current execution.

POST/api/v1/tasks/{taskId}/commands

Delivers a message to the thread, waking its workspace if it is asleep. Personal tokens may only send messages; other thread commands answer 403.

Every send names the execution it is for in the X-Statefold-Execution header. Read the current execution.id from Get a thread first: a fork or a harness switch changes it, and a send for an earlier execution answers 409 instead of reaching the wrong conversation.

Requires a personal API token with the tasks:send scope, sent as Authorization: Bearer over HTTPS.

Spends credits

Starting or waking a workspace runs a machine, billed per second at the project’s machine size.

Path parameters

taskIdstring (UUID)required: The thread. A thread that is not yours answers 404, never 403.

Headers

X-Statefold-Executionstringrequired: The thread's current execution.id.

Body

type"send"required: The only command a personal token may send.
idstring, 1–200 charactersrequired: A fresh identifier for this message, such as a UUID.
textstring, 1–200,000 charactersrequired: The message.
inputMode"queue" | "steer"optional: While the agent is working: queue waits for the current turn to finish, steer delivers into it.
skillIdsstring (UUID)[], up to 20optional: Skills from your library to use for this message.
skill"setup-repo"optional: Run the built-in repository setup skill with this message.
attachmentsobject[]optional: Inline attachments, as the browser composer sends them. Most scripts leave this out.

Returns

200 OK with a JSON array of the transcript updates produced when the message was admitted. It is not the agent's reply: poll Get a thread for statusSummary.

Errors

Errors are JSON: { "version": 1, "error": { "code", "message" } }. See Errors for retry advice.

400invalid_request: The body is not a valid command, the execution header is missing or malformed, or the thread rejected the message as invalid.
401unauthorized: The bearer token is missing, invalid or revoked.
403forbidden: The token does not have the tasks:send scope, or the account is suspended.
403forbidden: The command is not send, or the request came from a browser origin Statefold does not trust.
404not_found: The thread is not yours.
409conflict: The execution is not the thread's current one, or the thread cannot take the message in its current state. Read the thread again before retrying.
502unavailable: The thread answered with something Statefold could not read. Retry.