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

> Every endpoint bap-engine exposes.

bap-engine exposes a single HTTP API on `:8000`. Every endpoint
except `/health` requires authentication via `X-Platform-Key`. Admin
endpoints additionally require `X-Admin-Key`.

## Conventions

* **Base URL** — your deployment's URL. No version prefix.
* **Auth header** — `X-Platform-Key: <key>` on every product call.
  `X-Admin-Key: <key>` on admin calls.
* **Content type** — `application/json` for request bodies.
* **Errors** — non-2xx responses include `{"error": {"code": "...",
  "message": "..."}}`. See [Errors](./errors).

## Endpoints by category

### Engine lifecycle

| Method   | Path                            | Purpose                             |
| -------- | ------------------------------- | ----------------------------------- |
| `POST`   | `/engines/provision`            | Create a new engine for a user.     |
| `DELETE` | `/engines/{user_id}`            | Destroy a user's engine.            |
| `POST`   | `/engines/{user_id}/start`      | Start a stopped or sleeping engine. |
| `POST`   | `/engines/{user_id}/stop`       | Stop a running engine.              |
| `POST`   | `/engines/{user_id}/rotate-key` | Rotate the engine's API key.        |

[Reference →](./endpoints/lifecycle)

### Discovery and admission

| Method | Path                       | Purpose                                           |
| ------ | -------------------------- | ------------------------------------------------- |
| `GET`  | `/engines/{user_id}`       | Get engine info.                                  |
| `POST` | `/engines/{user_id}/admit` | Primary entry point. Auto-provisions, auto-wakes. |

[Reference →](./endpoints/discovery)

### Fleet operations

| Method | Path       | Purpose                                 |
| ------ | ---------- | --------------------------------------- |
| `GET`  | `/engines` | List all engines for a product.         |
| `GET`  | `/status`  | Fleet health snapshot.                  |
| `GET`  | `/metrics` | Operational metrics over the last hour. |

[Reference →](./endpoints/fleet)

### Admin (requires `X-Admin-Key`)

| Method | Path                            | Purpose                    |
| ------ | ------------------------------- | -------------------------- |
| `POST` | `/products/register`            | Register a new product.    |
| `PUT`  | `/products/{product_id}/policy` | Update a product's policy. |

[Reference →](./endpoints/admin)

### Health

| Method | Path      | Purpose                                        |
| ------ | --------- | ---------------------------------------------- |
| `GET`  | `/health` | Orchestrator liveness check. No auth required. |

[Reference →](./endpoints/health)

## See also

* [Auth](./auth) — `X-Platform-Key` and `X-Admin-Key` flows.
* [Errors](./errors) — every error code and what it means.
* [Engine contract](../engine-contract) — what the orchestrator
  promises engines and vice versa.