> ## 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.

# API reference

> The complete HTTP API surface of the Engine, by category.

The Engine exposes a single HTTP API on the port your deployment chose
(default `8000`). Every endpoint other than `/health` requires
authentication via the `X-Engine-Key` header. Most write endpoints accept
JSON; the execution endpoint streams Server-Sent Events back to the
client.

## Conventions

* **Base URL** — your deployment's URL (no version prefix today).
* **Auth header** — `X-Engine-Key: <key>` on every request except `/health`.
* **Content type** — `application/json` for request bodies that have one.
* **Streaming** — `/execute` returns `text/event-stream` (SSE).
* **Errors** — non-2xx responses include a JSON body
  `{"error": "<code>", "message": "<human description>"}`. See
  [Errors](./errors).

## Endpoints by category

### Execution

| Method | Path                         | Purpose                                        |
| ------ | ---------------------------- | ---------------------------------------------- |
| `POST` | `/execute`                   | Run an agent turn against a task. Streams SSE. |
| `GET`  | `/execute/replay?after=<ts>` | Replay events after a timestamp (for resume).  |

[Reference →](./endpoints/execute)

### Human-in-the-loop

| Method | Path            | Purpose                                                |
| ------ | --------------- | ------------------------------------------------------ |
| `POST` | `/hitl/respond` | Answer an LLM question or approve a permission prompt. |
| `GET`  | `/hitl/pending` | List pending HITL requests.                            |

[Reference →](./endpoints/hitl)

### RPC

| Method | Path   | Purpose                                         |
| ------ | ------ | ----------------------------------------------- |
| `POST` | `/rpc` | Generic dispatcher for skill / tool invocation. |

[Reference →](./endpoints/rpc)

### Asset Directory (MCP connectors)

| Method   | Path                           | Purpose                     |
| -------- | ------------------------------ | --------------------------- |
| `GET`    | `/assets/servers`              | List available MCP servers. |
| `GET`    | `/assets/connections`          | List active connections.    |
| `POST`   | `/assets/connect`              | Initiate a connection.      |
| `POST`   | `/assets/callback`             | OAuth callback (internal).  |
| `GET`    | `/assets/oauth/callback`       | OAuth redirect target.      |
| `DELETE` | `/assets/connections/{ref_id}` | Disconnect.                 |

[Reference →](./endpoints/assets)

### Memory

| Method | Path                       | Purpose                                 |
| ------ | -------------------------- | --------------------------------------- |
| `POST` | `/memory/knowledge/search` | Search the knowledge store.             |
| `POST` | `/memory/episodes/search`  | Search episodes.                        |
| `POST` | `/memory/social/search`    | Search the social graph.                |
| `GET`  | `/memory/soul`             | Get the user's core soul.               |
| `GET`  | `/memory/soul/full`        | Get the full soul with metadata.        |
| `GET`  | `/memory/export`           | Export all memory as a portable bundle. |
| `POST` | `/memory/import`           | Import a memory bundle.                 |

[Reference →](./endpoints/memory)

### Skills

| Method   | Path             | Purpose                |
| -------- | ---------------- | ---------------------- |
| `GET`    | `/skills`        | List skills.           |
| `GET`    | `/skills/{name}` | Get a skill.           |
| `POST`   | `/skills/create` | Create a custom skill. |
| `PUT`    | `/skills/{name}` | Update a skill.        |
| `DELETE` | `/skills/{name}` | Delete a skill.        |

[Reference →](./endpoints/skills)

### Admin

| Method | Path                      | Purpose                                |
| ------ | ------------------------- | -------------------------------------- |
| `POST` | `/admin/reload-core-soul` | Reload the soul template from catalog. |
| `POST` | `/admin/reload-catalog`   | Reload agents / skills / tools.        |
| `POST` | `/admin/lc/trigger`       | Trigger a Learning Centre batch run.   |

[Reference →](./endpoints/admin)

### Observability

| Method | Path        | Purpose                                             |
| ------ | ----------- | --------------------------------------------------- |
| `GET`  | `/health`   | Health check. No auth required.                     |
| `POST` | `/feedback` | Submit feedback (correction, rating, error report). |

[Reference →](./endpoints/observability)

## Authentication

Every endpoint except `/health` requires the `X-Engine-Key` header. See
[Authentication](./auth) for how keys are issued, hashed, and rotated.

## Streaming

`POST /execute` returns Server-Sent Events. Each event has a type
(`text_delta`, `tool_call`, `tool_result`, `hitl_request`, etc.) and a
JSON `data` payload. The complete event catalog lives at
[Streaming events](./streaming-events).