# API reference

The complete, machine-readable definition of the Maetra API lives in `openapi.yaml` (OpenAPI 3.1). It covers Govern, Secure, Task Guard, Agents, and system operations.

> **Note**
> **Wiring the spec in GitBook.** Add the OpenAPI file as an API reference source: **Organization settings → Integrations → OpenAPI**, upload `openapi.yaml` (or point at a hosted URL), then insert an **OpenAPI block** on this page.


### Operations

All endpoints are served from `https://api.maetra.io` and require a [Bearer API key](https://maetra.io/docs/getting-started/authentication) unless noted.

#### Govern

| Method | Path                        | Scope                      | Docs                                      |
| ------ | --------------------------- | -------------------------- | ----------------------------------------- |
| `POST` | `/v1/checkpoints`           | `govern:checkpoints:write` | [Checkpoints](https://maetra.io/docs/govern-api/checkpoints) |
| `GET`  | `/v1/checkpoints/{id}`      | `govern:checkpoints:read`  | [Checkpoints](https://maetra.io/docs/govern-api/checkpoints) |
| `GET`  | `/v1/checkpoints/{id}/wait` | `govern:checkpoints:read`  | [Checkpoints](https://maetra.io/docs/govern-api/checkpoints) |
| `GET`  | `/v1/policies/active`       | `govern:policies:read`     | [Policies](https://maetra.io/docs/govern-api/policies)       |

#### Secure

| Method  | Path                    | Scope                   | Docs                                                |
| ------- | ----------------------- | ----------------------- | --------------------------------------------------- |
| `GET`   | `/v1/secure/rules`      | `secure:rules:read`     | [Rules](https://maetra.io/docs/secure-api/rules)                       |
| `POST`  | `/v1/secure/rules`      | `secure:rules:write`    | [Rules](https://maetra.io/docs/secure-api/rules)                       |
| `PATCH` | `/v1/secure/rules/{id}` | `secure:rules:write`    | [Rules](https://maetra.io/docs/secure-api/rules)                       |
| `POST`  | `/v1/secure/scan`       | `secure:scan:write`     | [Scanning content](https://maetra.io/docs/secure-api/scanning-content) |
| `GET`   | `/v1/secure/incidents`  | `secure:incidents:read` | [Incidents](https://maetra.io/docs/secure-api/incidents)               |

#### Agents

| Method | Path         | Scope                  | Docs                 |
| ------ | ------------ | ---------------------- | -------------------- |
| `GET`  | `/v1/agents` | `discover:agents:read` | [Agents](https://maetra.io/docs/agents) |

#### Task Guard

| Method | Path | Scope | Docs |
| ------ | ---- | ----- | ---- |
| `POST` | `/v1/task-guard/tools/{tool}` | Depends on tool | [Task Guard API](https://maetra.io/docs/task-guard-api) |
| `POST` | `/v1/task-guard/sessions` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/sessions/{sessionId}/user-events` | `task_guard:confirmations:write` + trusted credential | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}` | `task_guard:tasks:read` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}/context` | `task_guard:tasks:read` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/progress` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/pause` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/resume` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/cancel` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/complete` | `task_guard:tasks:write` | [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/checks` | `task_guard:checks:write` | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/tasks/{taskId}/changes` | `task_guard:checks:write` | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/explanation` | `task_guard:checks:write` | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/effects` | `task_guard:effects:write` | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/changes/{proposalId}/confirmation` | `task_guard:confirmations:write` + trusted credential | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/alignment/verify` | `task_guard:checks:write` | [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects) |

#### System

| Method | Path                     | Auth          | Docs                                                 |
| ------ | ------------------------ | ------------- | ---------------------------------------------------- |
| `GET`  | `/v1/ping`               | Any valid key | [Authentication](https://maetra.io/docs/getting-started/authentication) |
| `GET`  | `/.well-known/jwks.json` | None          | [Decision tokens](https://maetra.io/docs/govern-api/decision-tokens)    |