> ## Documentation Index
> Fetch the complete documentation index at: https://internal.september.wtf/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```http theme={null}
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](../../capabilities/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](../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:

```http theme={null}
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](../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](../streaming-events) — every event type.
* [The agent loop](../../agents-and-tools/agent-loop) — what's happening
  on the server during a turn.
* [HITL endpoints](./hitl) — answer questions the agent asks.