# API reference

The API is at `https://mechane-api.mechane.workers.dev`. Every request needs
`Authorization: Bearer <workspace-key>`. Bodies are JSON; unknown properties are rejected. Errors are JSON
objects with an `error` message.

| Method | Path                                 | Does                                                                          |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------- |
| POST   | `/v1/mechs`                          | Create `{ id, model, instructions?, reasoningEffort? }`. Safe to retry.       |
| GET    | `/v1/mechs?after=<id>`               | List up to 100 mechs as `{ items: [{ id }], next }`.                          |
| GET    | `/v1/mechs/{id}`                     | Read the profile, settings, current run, and checkpoint reference.            |
| PATCH  | `/v1/mechs/{id}`                     | Update `{ instructions?, reasoningEffort? }` for future runs.                 |
| POST   | `/v1/mechs/{id}/runs`                | Start `{ input, settings? }` with an `Idempotency-Key` header. Returns `202`. |
| GET    | `/v1/mechs/{id}/runs/{runId}`        | Read the run's status, output, and resolved settings.                         |
| GET    | `/v1/mechs/{id}/runs/{runId}/events` | Stream events. Resume with `Last-Event-ID` or `?after=<id>`.                  |
| POST   | `/v1/mechs/{id}/runs/{runId}/cancel` | Request cancellation. Safe to repeat.                                         |
| GET    | `/v1/mechs/{id}/credits`             | Read the mech's balance.                                                      |
| GET    | `/v1/mechs/{id}/usage`               | List the mech's recent usage.                                                 |

## Status codes

| Code  | Meaning                                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------------------------------- |
| `202` | The run was accepted.                                                                                                  |
| `400` | The request body or parameters are invalid.                                                                            |
| `401` | The key is missing, unknown, or revoked.                                                                               |
| `404` | No mech or run with that name in this workspace.                                                                       |
| `409` | The mech is busy, the name exists with a different profile, or an idempotency key was reused with a different request. |