> For the complete documentation index, see [llms.txt](https://docs.maetra.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maetra.io/reference/api-reference.md).

# API reference

The complete, machine-readable definition of the Maetra API lives in `openapi.yaml` (OpenAPI 3.1). GitBook renders it into interactive, try-it reference docs.

{% hint style="info" %}
**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.
{% endhint %}

### Operations

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

#### Govern

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

#### Secure

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

#### Agents

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

#### System

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