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 unless noted.
Govern
| Method | Path | Scope | Docs |
|---|---|---|---|
POST | /v1/checkpoints | govern:checkpoints:write | Checkpoints |
GET | /v1/checkpoints/{id} | govern:checkpoints:read | Checkpoints |
GET | /v1/checkpoints/{id}/wait | govern:checkpoints:read | Checkpoints |
GET | /v1/policies/active | govern:policies:read | Policies |
Secure
| Method | Path | Scope | Docs |
|---|---|---|---|
GET | /v1/secure/rules | secure:rules:read | Rules |
POST | /v1/secure/rules | secure:rules:write | Rules |
PATCH | /v1/secure/rules/{id} | secure:rules:write | Rules |
POST | /v1/secure/scan | secure:scan:write | Scanning content |
GET | /v1/secure/incidents | secure:incidents:read | Incidents |
Agents
| Method | Path | Scope | Docs |
|---|---|---|---|
GET | /v1/agents | discover:agents:read | Agents |
Task Guard
| Method | Path | Scope | Docs |
|---|---|---|---|
POST | /v1/task-guard/tools/{tool} | Depends on tool | Task Guard API |
POST | /v1/task-guard/sessions | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/sessions/{sessionId}/user-events | task_guard:confirmations:write + trusted credential | Tasks and context |
GET | /v1/task-guard/tasks/{taskId} | task_guard:tasks:read | Tasks and context |
GET | /v1/task-guard/tasks/{taskId}/context | task_guard:tasks:read | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/progress | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/pause | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/resume | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/cancel | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/complete | task_guard:tasks:write | Tasks and context |
POST | /v1/task-guard/tasks/{taskId}/checks | task_guard:checks:write | Alignment and effects |
POST | /v1/task-guard/tasks/{taskId}/changes | task_guard:checks:write | Alignment and effects |
POST | /v1/task-guard/checks/{checkId}/explanation | task_guard:checks:write | Alignment and effects |
POST | /v1/task-guard/checks/{checkId}/effects | task_guard:effects:write | Alignment and effects |
POST | /v1/task-guard/changes/{proposalId}/confirmation | task_guard:confirmations:write + trusted credential | Alignment and effects |
POST | /v1/task-guard/alignment/verify | task_guard:checks:write | Alignment and effects |
System
| Method | Path | Auth | Docs |
|---|---|---|---|
GET | /v1/ping | Any valid key | Authentication |
GET | /.well-known/jwks.json | None | Decision tokens |