# Referencia de API

La definición completa y legible por máquina de la Maetra API vive en `openapi.yaml` (OpenAPI 3.1). Cubre a Govern, Secure, Task Guard, Agentes y operaciones del sistema.

> **Note**
> **Sacando la especificaciones en GitBook.** Añada el archivo OpenAPI como fuente de referencia de API: **Configuración de la organización → Integraciones → OpenAPI**, subir `openapi.yaml` (o punto en una URL hospedada), a continuación, insertar un **Bloque OpenAPI** en esta página.


### Operaciones

Todos los puntos finales se sirven desde `https://api.maetra.io` y requieren un [Clave de la API de portador](https://maetra.io/es/docs/getting-started/authentication) a menos que se indique.

#### Govern

| Método | Camino | Ámbito | Docs |
| ------ | --------------------------- | -------------------------- | ----------------------------------------- |
| `POST` | `/v1/checkpoints` | `govern:checkpoints:write` | [Puntos de control](https://maetra.io/es/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}` | `govern:checkpoints:read` | [Puntos de control](https://maetra.io/es/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}/wait` | `govern:checkpoints:read` | [Puntos de control](https://maetra.io/es/docs/govern-api/checkpoints) |
| `GET` | `/v1/policies/active` | `govern:policies:read` | [Políticas](https://maetra.io/es/docs/govern-api/policies) |

#### Secure

| Método | Camino | Ámbito | Docs |
| ------- | ----------------------- | ----------------------- | --------------------------------------------------- |
| `GET` | `/v1/secure/rules` | `secure:rules:read` | [Reglas](https://maetra.io/es/docs/secure-api/rules) |
| `POST` | `/v1/secure/rules` | `secure:rules:write` | [Reglas](https://maetra.io/es/docs/secure-api/rules) |
| `PATCH` | `/v1/secure/rules/{id}` | `secure:rules:write` | [Reglas](https://maetra.io/es/docs/secure-api/rules) |
| `POST` | `/v1/secure/scan` | `secure:scan:write` | [Contenido de exploración](https://maetra.io/es/docs/secure-api/scanning-content) |
| `GET` | `/v1/secure/incidents` | `secure:incidents:read` | [Incidentes](https://maetra.io/es/docs/secure-api/incidents) |

#### Agentes

| Método | Camino | Ámbito | Docs |
| ------ | ------------ | ---------------------- | -------------------- |
| `GET` | `/v1/agents` | `discover:agents:read` | [Agentes](https://maetra.io/es/docs/agents) |

#### Task Guard

| Método | Camino | Ámbito | Docs |
| ------ | ---- | ----- | ---- |
| `POST` | `/v1/task-guard/tools/{tool}` | Depende de la herramienta | [Task Guard API](https://maetra.io/es/docs/task-guard-api) |
| `POST` | `/v1/task-guard/sessions` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/sessions/{sessionId}/user-events` | `task_guard:confirmations:write` + confianza credencial | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}` | `task_guard:tasks:read` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}/context` | `task_guard:tasks:read` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/progress` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/pause` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/resume` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/cancel` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/complete` | `task_guard:tasks:write` | [Tareas y contexto](https://maetra.io/es/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/checks` | `task_guard:checks:write` | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/tasks/{taskId}/changes` | `task_guard:checks:write` | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/explanation` | `task_guard:checks:write` | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/effects` | `task_guard:effects:write` | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/changes/{proposalId}/confirmation` | `task_guard:confirmations:write` + confianza credencial | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/alignment/verify` | `task_guard:checks:write` | [Alineación y efectos](https://maetra.io/es/docs/task-guard-api/alignment-and-effects) |

#### Sistema

| Método | Camino | Auth | Docs |
| ------ | ------------------------ | ------------- | ---------------------------------------------------- |
| `GET` | `/v1/ping` | Cualquier clave válida | [Autenticación](https://maetra.io/es/docs/getting-started/authentication) |
| `GET` | `/.well-known/jwks.json` | Ninguno | [Decision tokens](https://maetra.io/es/docs/govern-api/decision-tokens) |