# API-Referenz

Die vollständige, maschinenlesbare Definition der Maetra API lebt in `openapi.yaml` (OpenAPI 3.1). Es umfasst Govern, Secure, Task Guard, Agenten und Systemoperationen.

> **Note**
> **Verdrahtung der Spezifikation in GitBook.** Fügen Sie die OpenAPI-Datei als API-Referenzquelle hinzu: **Organisationseinstellungen → Integrationen → OpenAPI**, Upload `openapi.yaml` (oder zeigen Sie auf eine gehostete URL), dann fügen Sie eine **OpenAPI-Block** auf dieser Seite.


### Betrieb

Alle Endpunkte werden von `https://api.maetra.io` und erfordern eine [Bearer API Schlüssel](https://maetra.io/de/docs/getting-started/authentication) Sofern nicht vermerkt.

#### Govern

| Methode | Wegstrecke | Anwendungsbereich | Docs |
| ------ | --------------------------- | -------------------------- | ----------------------------------------- |
| `POST` | `/v1/checkpoints` | `govern:checkpoints:write` | [Kontrollpunkte](https://maetra.io/de/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}` | `govern:checkpoints:read` | [Kontrollpunkte](https://maetra.io/de/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}/wait` | `govern:checkpoints:read` | [Kontrollpunkte](https://maetra.io/de/docs/govern-api/checkpoints) |
| `GET` | `/v1/policies/active` | `govern:policies:read` | [Politiken](https://maetra.io/de/docs/govern-api/policies) |

#### Secure

| Methode | Wegstrecke | Anwendungsbereich | Docs |
| ------- | ----------------------- | ----------------------- | --------------------------------------------------- |
| `GET` | `/v1/secure/rules` | `secure:rules:read` | [Vorschriften](https://maetra.io/de/docs/secure-api/rules) |
| `POST` | `/v1/secure/rules` | `secure:rules:write` | [Vorschriften](https://maetra.io/de/docs/secure-api/rules) |
| `PATCH` | `/v1/secure/rules/{id}` | `secure:rules:write` | [Vorschriften](https://maetra.io/de/docs/secure-api/rules) |
| `POST` | `/v1/secure/scan` | `secure:scan:write` | [Scannerinhalte](https://maetra.io/de/docs/secure-api/scanning-content) |
| `GET` | `/v1/secure/incidents` | `secure:incidents:read` | [Zwischenfälle](https://maetra.io/de/docs/secure-api/incidents) |

#### Agenten

| Methode | Wegstrecke | Anwendungsbereich | Docs |
| ------ | ------------ | ---------------------- | -------------------- |
| `GET` | `/v1/agents` | `discover:agents:read` | [Agenten](https://maetra.io/de/docs/agents) |

#### Task Guard

| Methode | Wegstrecke | Anwendungsbereich | Docs |
| ------ | ---- | ----- | ---- |
| `POST` | `/v1/task-guard/tools/{tool}` | Abhängig vom Werkzeug | [Task Guard API](https://maetra.io/de/docs/task-guard-api) |
| `POST` | `/v1/task-guard/sessions` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/sessions/{sessionId}/user-events` | `task_guard:confirmations:write` + Trusted Credential | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}` | `task_guard:tasks:read` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}/context` | `task_guard:tasks:read` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/progress` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/pause` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/resume` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/cancel` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/complete` | `task_guard:tasks:write` | [Aufgaben und Kontext](https://maetra.io/de/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/checks` | `task_guard:checks:write` | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/tasks/{taskId}/changes` | `task_guard:checks:write` | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/explanation` | `task_guard:checks:write` | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/effects` | `task_guard:effects:write` | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/changes/{proposalId}/confirmation` | `task_guard:confirmations:write` + Trusted Credential | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/alignment/verify` | `task_guard:checks:write` | [Ausrichtung und Auswirkungen](https://maetra.io/de/docs/task-guard-api/alignment-and-effects) |

#### System

| Methode | Wegstrecke | Authen | Docs |
| ------ | ------------------------ | ------------- | ---------------------------------------------------- |
| `GET` | `/v1/ping` | Jeder gültige Schlüssel | [Authentifizierung](https://maetra.io/de/docs/getting-started/authentication) |
| `GET` | `/.well-known/jwks.json` | Keine | [Entscheidungsmarken](https://maetra.io/de/docs/govern-api/decision-tokens) |