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

# Přehled REST API ClearPolicy

> REST API ClearPolicy komunikuje přes HTTPS a vrací JSON. Zjistěte základní URL, verzování, formát stránkování, formát ID a chybové odpovědi.

REST API ClearPolicy Vám dává přístup z kódu k lidem, skupinám, dokumentům a žádostem o potvrzení Vaší organizace. Všechny endpointy komunikují přes HTTPS a vrací JSON.

## Základní URL

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

Předpona cesty API (`/api/v1`) je součástí každé URL požadavku. Aktuální a jediná verze je `v1`.

## Ověření

Všechny endpointy vyžadují platný bearer token API. Token předejte v hlavičce `Authorization`:

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

Návod na vytvoření tokenu najdete v [Ověření](/api/authentication).

<Note>
  Vaše organizace musí mít aktivní předplatné, nebo být ve zkušebním období. Když zkušební období vypršelo nebo předplatné není aktivní, všechny požadavky API vrátí odpověď `402 Payment Required`.
</Note>

## Přístup podle role

Přístup k API se řídí Vaší rolí v ClearPolicy. Vlastníci a správci organizace mohou vytvářet tokeny API a používat endpointy lidí, skupin, dokumentů a žádostí o potvrzení. Tokeny vázané na správce skupiny mohou použít `GET /me` k ověření tokenu a organizace. Ostatní endpointy REST API vrátí `403 Forbidden`.

## Formát odpovědí

Všechny odpovědi jsou JSON. Úspěšné odpovědi vrací požadovaný zdroj nebo kolekci přímo v těle odpovědi.

## ID

Všechna ID zdrojů jsou [ULID](https://github.com/ulid/spec) — řetězcové identifikátory, které lze řadit lexikograficky. Zapisují se malými písmeny, například:

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

## Stránkování

Endpointy seznamů vrací stránkované výsledky. Odpověď obsahuje pole `data` spolu s objekty `links` a `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
  }
}
```

Výsledky procházíte parametry dotazu `page` a `per_page`. `per_page` přijímá hodnoty od 1 do 100. Výchozí hodnota je 25.

## Chyby

Chyby vrací JSON s polem `error`, které popisuje problém:

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

Běžné stavové kódy HTTP:

| Stav                       | Význam                                                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | Požadavek uspěl.                                                                                                              |
| `201 Created`              | Zdroj byl úspěšně vytvořen.                                                                                                   |
| `400 Bad Request`          | Požadavek byl neplatný (např. dokument není zveřejněný).                                                                      |
| `401 Unauthorized`         | Chybí přístupový token, nebo je neplatný.                                                                                     |
| `402 Payment Required`     | Zkušební období Vaší organizace vypršelo, nebo předplatné není aktivní. Přejděte na stránku fakturace a předplaťte si službu. |
| `403 Forbidden`            | Token nemá potřebná oprávnění.                                                                                                |
| `404 Not Found`            | Požadovaný zdroj ve Vaší organizaci neexistuje.                                                                               |
| `422 Unprocessable Entity` | Validace selhala — zkontrolujte parametry požadavku.                                                                          |
| `429 Too Many Requests`    | Překročen limit počtu požadavků — počkejte a zkuste to znovu.                                                                 |

## Omezení počtu požadavků

Každý token API je omezený na **60 požadavků za minutu**. Limity platí na token, ne na organizaci. Několik tokenů má proto každý vlastní kvótu.

Když limit překročíte, API vrátí `429 Too Many Requests`. Odpovědi obsahují hlavičky `Retry-After` a `X-RateLimit-*`, abyste věděli, kdy zkusit znovu. Při opakování používejte exponenciální backoff.