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
Body
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:
Task semantics
Atask_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 newmessage. 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.
Resuming a stream
If your client disconnects mid-turn, the Engine continues running and buffers events until the channel state TTL expires. Reconnect with: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
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.