POST /execute

Run an agent turn against a task. Streams Server-Sent Events.

POST /execute is the heart of the Engine. You send a message and a task_id; the Engine streams back the agent’s reasoning, tool calls, results, and final answer.

Request

POST /execute
X-Engine-Key: <key>
Content-Type: application/json

{
  "message": "Find the latest commit and summarize it.",
  "task_id": "task-001",
  "media": [],
  "direct": false,
  "edit_message_id": null,
  "retry_message_id": null
}

Body

Field	Type	Required	Default	Purpose
message	string	yes	—	The user’s message.
task_id	string	yes	—	Conversation thread identifier. Reuse to continue, change to start fresh.
media	array	no	[]	Attached media blocks (images, files). See Multimodal.
direct	boolean	no	false	Skip planning and run the loop directly.
edit_message_id	string	no	null	Replace a prior message in the thread.
retry_message_id	string	no	null	Retry from a prior message.

Response

Content-Type: text/event-stream. The body is a sequence of SSE events. See Streaming events for the complete catalog.

A typical successful turn emits:

event: thread_lifecycle
data: {"phase":"started", ...}

event: text_delta
data: {"text":"Looking up the latest commit..."}

event: tool_call
data: {"tool":"bash","input":{"command":"git log -1 --format=%H"}}

event: tool_result
data: {"output":"8c44ab1..."}

event: text_delta
data: {"text":"The latest commit is 8c44ab1, which..."}

event: thread_lifecycle
data: {"phase":"completed", ...}

Task semantics

A task_id is a conversation thread. Reusing one continues the same conversation; the Engine pulls past turns, working memory, and any relevant long-term memory automatically.

• Pick any string. UUIDs are common but not required.
• Reuse the same ID across turns to maintain continuity.
• Use a new ID to start a fresh conversation.
• Tasks live indefinitely. The brain stores their state.

Editing and retrying

edit_message_id and retry_message_id let you rewind a thread:

• edit_message_id — replace the message identified by that ID with the new message. Subsequent state from that point is invalidated; the Engine re-runs from the edit.
• retry_message_id — keep all messages, but re-run the loop from the given message with whatever state existed up to that point.

Both are useful for “regenerate” UIs.

Resuming a stream

If your client disconnects mid-turn, the Engine continues running and buffers events until the channel state TTL expires. Reconnect with:

GET /execute/replay?after=<unix_ms>
X-Engine-Key: <key>

after is a millisecond Unix timestamp. The Engine replays every event emitted on the current task after that timestamp. Use 0 to replay everything available.

The buffer’s lifetime is controlled by CHANNEL_STATE_TTL_ACTIVE (default 3 hours) and CHANNEL_STATE_TTL_HITL (default 72 hours).

Errors

Status	When
400	Missing message or task_id.
401	Missing or invalid X-Engine-Key.
409	Another /execute is already running on this task_id.
500	Unexpected error. The stream emits an error event before closing.

In-stream errors arrive as event: error and end the stream. See Errors for codes and retry guidance.

Rate limits

The Engine itself doesn’t impose a rate limit beyond what the upstream LLM provider does. Concurrency per task is one — a second /execute against a running task returns 409.

See also

• Streaming events — every event type.
• The agent loop — what’s happening on the server during a turn.
• HITL endpoints — answer questions the agent asks.