> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpolicy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Übersicht über die ClearPolicy-REST-API

> Die ClearPolicy-REST-API kommuniziert über HTTPS und gibt JSON zurück. Erfahre mehr über die Basis-URL, Versionierung, das Paginierungsformat, das ID-Format und Fehlerantworten.

Die ClearPolicy-REST-API ermöglicht dir den programmgesteuerten Zugriff auf die Personen, Dokumente und Bestätigungsanfragen deiner Organisation. Alle Endpunkte kommunizieren über HTTPS und geben JSON zurück.

## Basis-URL

```text theme={null}
https://api.clearpolicy.app/api/v1
```

Das API-Pfadpräfix (`/api/v1`) ist in jeder Anfrage-URL enthalten. Die aktuelle und einzige Version ist `v1`.

## Authentifizierung

Alle Endpunkte erfordern ein gültiges API-Bearer-Token. Übergib das Token im `Authorization`-Header:

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Siehe [Authentifizierung](/api/authentication) für Anweisungen zum Erstellen eines Tokens.

<Note>
  Deine Organisation muss ein aktives Abonnement haben oder sich innerhalb des Testzeitraums befinden. Wenn dein Test abgelaufen oder dein Abonnement inaktiv ist, geben alle API-Anfragen eine Antwort `402 Payment Required` zurück.
</Note>

## Zugriff nach Rolle

Der API-Zugriff folgt deiner Rolle in ClearPolicy. Eigentümer und Administratoren der Organisation können API-Tokens erstellen und die Endpunkte für Personen, Dokumente und Bestätigungsanfragen nutzen. Tokens, die an Gruppenleitende gebunden sind, können `GET /me` verwenden, um den Token und die Organisation zu bestätigen, aber andere REST-API-Endpunkte geben `403 Forbidden` zurück.

## Antwortformat

Alle Antworten sind JSON. Erfolgreiche Antworten geben die angeforderte Ressource oder Sammlung direkt im Antwortkörper zurück.

## IDs

Alle Ressourcen-IDs sind [ULIDs](https://github.com/ulid/spec) — lexikografisch sortierbare String-Bezeichner. Sie werden als Kleinbuchstabenzeichenfolgen dargestellt, zum Beispiel:

```text theme={null}
01kg82xqfx6fvr046d15hnfmjv
```

## Paginierung

Listen-Endpunkte geben paginierte Ergebnisse zurück. Die Antwort enthält ein `data`-Array zusammen mit `links`- und `meta`-Objekten:

```json theme={null}
{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}
```

Verwende die Abfrageparameter `page` und `per_page`, um durch die Ergebnisse zu navigieren. `per_page` akzeptiert Werte zwischen 1 und 100, der Standardwert ist 25.

## Fehler

Fehler geben JSON mit einem `error`-Feld zurück, das das Problem beschreibt:

```json theme={null}
{
  "error": "Person not found."
}
```

Gängige HTTP-Statuscodes:

| Status                     | Bedeutung                                                                                                                      |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `200 OK`                   | Anfrage erfolgreich.                                                                                                           |
| `201 Created`              | Ressource erfolgreich erstellt.                                                                                                |
| `400 Bad Request`          | Die Anfrage war ungültig (z. B. Dokument nicht veröffentlicht).                                                                |
| `401 Unauthorized`         | Zugriffstoken fehlt oder ist ungültig.                                                                                         |
| `402 Payment Required`     | Der Test deiner Organisation ist abgelaufen oder das Abonnement ist inaktiv. Besuche deine Abrechnungsseite, um zu abonnieren. |
| `403 Forbidden`            | Token verfügt nicht über die erforderlichen Berechtigungen.                                                                    |
| `404 Not Found`            | Die angeforderte Ressource existiert in deiner Organisation nicht.                                                             |
| `422 Unprocessable Entity` | Validierung fehlgeschlagen — überprüfe die Anfrageparameter.                                                                   |
| `429 Too Many Requests`    | Ratenlimit überschritten — warte und versuche es erneut.                                                                       |

## Ratenbegrenzung

Jedes API-Token ist auf **60 Anfragen pro Minute** begrenzt. Die Limits gelten pro Token, nicht pro Organisation — mehrere Tokens haben jeweils ihr eigenes Kontingent.

Wenn du das Limit überschreitest, gibt die API `429 Too Many Requests` zurück. Antworten enthalten die Header `Retry-After` und `X-RateLimit-*`, damit du erkennst, wann du es erneut versuchen kannst. Verwende beim Wiederholen ein exponentielles Backoff.