> ## 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.

# Aperçu de l'API REST ClearPolicy

> L'API REST ClearPolicy communique via HTTPS et renvoie du JSON. Découvrez l'URL de base, la gestion des versions, le format de pagination, le format des identifiants et les réponses d'erreur.

L'API REST ClearPolicy vous donne un accès programmatique aux personnes, documents et demandes de validation de votre organisation. Tous les points de terminaison communiquent via HTTPS et renvoient du JSON.

## URL de base

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

Le préfixe du chemin de l'API (`/api/v1`) est inclus dans chaque URL de requête. La version actuelle et unique est `v1`.

## Authentification

Tous les points de terminaison nécessitent un jeton porteur API valide. Passez le jeton dans l'en-tête `Authorization` :

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

Consultez [Authentification](/api/authentication) pour les instructions sur la création d'un jeton.

<Note>
  Votre organisation doit disposer d'un abonnement actif ou se trouver dans sa période d'essai. Si votre essai a expiré ou si votre abonnement est inactif, toutes les requêtes API renvoient une réponse `402 Payment Required`.
</Note>

## Accès par rôle

L'accès à l'API suit votre rôle dans ClearPolicy. Les propriétaires et administrateurs d'organisation peuvent créer des jetons API et utiliser les points de terminaison des personnes, documents et demandes de validation. Les jetons liés à des gestionnaires de groupe peuvent utiliser `GET /me` pour confirmer le jeton et l'organisation, mais les autres points de terminaison de l'API REST renvoient `403 Forbidden`.

## Format des réponses

Toutes les réponses sont au format JSON. Les réponses réussies renvoient la ressource ou la collection demandée directement dans le corps de la réponse.

## Identifiants

Tous les identifiants de ressources sont des [ULID](https://github.com/ulid/spec) — des identifiants en chaîne triables lexicographiquement. Ils sont représentés sous forme de chaînes en minuscules, par exemple :

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

## Pagination

Les points de terminaison de liste renvoient des résultats paginés. La réponse comprend un tableau `data` ainsi que des objets `links` et `meta` :

```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
  }
}
```

Utilisez les paramètres de requête `page` et `per_page` pour naviguer dans les résultats. `per_page` accepte des valeurs comprises entre 1 et 100, la valeur par défaut étant 25.

## Erreurs

Les erreurs renvoient du JSON avec un champ `error` décrivant le problème :

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

Codes de statut HTTP courants :

| Statut                     | Signification                                                                                                              |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | Requête réussie.                                                                                                           |
| `201 Created`              | Ressource créée avec succès.                                                                                               |
| `400 Bad Request`          | La requête était invalide (par ex. document non publié).                                                                   |
| `401 Unauthorized`         | Jeton d'accès manquant ou invalide.                                                                                        |
| `402 Payment Required`     | L'essai de votre organisation a expiré ou l'abonnement est inactif. Consultez votre page de facturation pour vous abonner. |
| `403 Forbidden`            | Le jeton ne dispose pas des autorisations requises.                                                                        |
| `404 Not Found`            | La ressource demandée n'existe pas dans votre organisation.                                                                |
| `422 Unprocessable Entity` | Échec de la validation — vérifiez les paramètres de la requête.                                                            |
| `429 Too Many Requests`    | Limite de débit dépassée — attendez et réessayez.                                                                          |

## Limitation de débit

Chaque jeton d'API est limité à **60 requêtes par minute**. Les limites s'appliquent par jeton, et non par organisation — plusieurs jetons ont chacun leur propre quota.

Si vous dépassez la limite, l'API renvoie `429 Too Many Requests`. Les réponses incluent les en-têtes `Retry-After` et `X-RateLimit-*` pour indiquer quand réessayer. Utilisez un backoff exponentiel lors des tentatives.