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

# Control plane

> What operators talk to: approvals, debug sessions, leases, agents, audit, and the live event stream.

Authenticate with an operator token:

```
Authorization: Bearer wc_live_…
```

Every route names the capability it requires, so one cannot be added without deciding who may call it.

| Capability | Held by |
| - | - |
| `read` | every role |
| `review` | reviewer, operator, owner |
| `manage` | operator, owner |

## Pending approvals

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/pending` | read |
| `POST` | `/api/v1/pending/{id}/approve` | review |
| `POST` | `/api/v1/pending/{id}/reject` | review |

Approve and reject accept `{"reason": "…"}`. The reason reaches the agent on a rejection and the audit record either way.

A pending entry carries the statement as it will run, the agent's stated reason, class and verb, resources, hazards, whether it is bounded, the estimated records, the deadline, its `preview`, and the `fence` protecting it.

## Debug sessions

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/debug/sessions` | read |
| `POST` | `/api/v1/debug/sessions` | manage |
| `GET` | `/api/v1/debug/sessions/{id}` | read |
| `GET` | `/api/v1/debug/sessions/{id}/export` | read |
| `POST` | `/api/v1/debug/sessions/{id}/continue` | review |
| `POST` | `/api/v1/debug/sessions/{id}/stop` | review |

Start with `{"connection":"shop","classes":["write"],"unbounded_only":false,"agents":["agent:support"],"ttl_minutes":30}`. Stopping refuses whatever is still waiting. See [Debug Mode](https://warden.buildlab.in/operate/debug-mode.md).

## Leases

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/leases` | read |
| `GET` | `/api/v1/leases/{id}` | read |
| `POST` | `/api/v1/leases/{id}/renew` | manage |
| `POST` | `/api/v1/leases/{id}/revoke` | review |
| `POST` | `/api/v1/agents/{id}/revoke-leases` | review |

Revocation is a review capability on purpose: severing access mid-incident is what a reviewer is on call to do.

## Agents

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/agents` | read |
| `POST` | `/api/v1/agents/{id}/freeze` | manage |
| `POST` | `/api/v1/agents/{id}/unfreeze` | manage |

Listing an agent shows its breaker state, signal counts, and why it was frozen. Reinstating requires a reason, which is recorded — that judgement is the most useful thing in the record when the same agent trips again next week.

> [!NOTE]
>
> Revoking a lease severs the current credential; it does not lock the agent out, because a lease is not an authentication credential. To stop an agent entirely, freeze it and revoke its leases.

## Connections

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/connections` | read |
| `GET` | `/api/v1/connections/{name}` | read |
| `GET` | `/api/v1/connections/{name}/schema` | read |

A connection summary includes its engine, health, policy mode, posture, and **the capability ladder** — the page a security reviewer reads, in the same terms the CLI prints.

## Audit

| Method | Path | Capability |
| - | - | - |
| `GET` | `/api/v1/audit` | read |
| `GET` | `/api/v1/audit/verify` | read |

Filters: `agent`, `task`, `type`, `effect`, `outcome`, `limit`, `after`. Verify returns HTTP 409 when the chain is broken. See [audit](https://warden.buildlab.in/operate/audit.md).

## Events

`GET /api/v1/events` (read) is a server-sent event stream of `paused` and `resolved` notifications, which is what makes the operator view live.

It is one-directional — every action goes back over an ordinary POST — so SSE carries the same `Authorization` header as everything else and needs no second authentication path. A subscriber that connects mid-session is sent everything already pending first. A subscriber that falls behind loses events rather than stalling the gateway: a live view missing a frame is survivable, a browser holding up every agent's database access is not.

## Health

`GET /health` is unauthenticated. It reports that the process is up and how many connections are configured, and nothing about what it governs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.