# API ZRAZU — огляд для розробників

> Базова адреса, вхід за ключем, ідемпотентність, формат помилок і ліміти API ZRAZU — для своїх скриптів, інтеграцій і ШІ-агентів.

URL: https://zrazu.com/docs/api-overview/

API ZRAZU дає скриптам і програмам те, що ви робите в кабінеті: прочитати список доменів, зони DNS і сертифікати, поставити домен на моніторинг. Працює за ключем, який ви випускаєте самі.

Окремо є [MCP для ШІ-агентів](https://zrazu.com/docs/api-mcp.md): він відкритий, без ключа, але лише читає й показує паспорт публічного домену.

## Що вміє API за ключем

Базова адреса: `https://api.zrazu.com/v1`.

| Група | Що можна |
| --- | --- |
| Ключ | `GET /v1/api-keys/current` — які права, домени й строк має цей ключ |
| Домени | `GET /v1/domains` — список доменів організації зі строком, автопродовженням і замками |
| Моніторинг | `GET /v1/monitoring`, `POST /v1/monitoring`, `DELETE /v1/monitoring/{name}` — читати, ставити й знімати імена |
| DNS | `GET /v1/dns/zones`, `GET /v1/dns/zones/{name}`; зміна записів і нові зони — див. [домени й DNS через API](https://zrazu.com/docs/api-domains-dns.md) |
| SSL | `GET /v1/ssl/catalog`, `GET /v1/ssl/certificates`, файли сертифіката, замовлення й перевипуск |
| Баланс | `GET /v1/balance` — баланс організації |

Що доступно саме вашому ключу, залежить від його прав: див. [ключі API](https://zrazu.com/docs/api-keys.md).

Реєструвати й продовжувати домени, змінювати контакти й замки, отримувати код перенесення через API не можна. Це свідомо: такі дії лишаються в кабінеті.

## Вхід за ключем

Ключ передають лише в заголовку:

```sh
curl -H "Authorization: Bearer zr_live_..." https://api.zrazu.com/v1/api-keys/current
```

Ключ в адресі запиту (`?key=…`) відхиляється: адреси потрапляють у журнали серверів і браузерів. Ключ починається з `zr_live_`. Ключ, який вставили в код сторінки сайту, не спрацює: API не дозволяє запити з чужих сторінок браузера, і це навмисно.

## Безпечний повтор змін

Кожен запит, що щось змінює (`POST`, `PUT`, `DELETE`), потребує заголовка `Idempotency-Key` — довільний рядок до 120 символів, наприклад UUID.

```sh
curl -X POST https://api.zrazu.com/v1/monitoring \
  -H "Authorization: Bearer zr_live_..." \
  -H "Idempotency-Key: 6f1d8c0e-5b2a-4c1f-9a3e-0d7b2e4a1c11" \
  -H "Content-Type: application/json" \
  -d '{"names": ["example.com.ua"]}'
```

- Повторний запит із тим самим ключем протягом 24 годин повертає першу відповідь із заголовком `Idempotent-Replayed: true` — друга зміна не виконується.
- Той самий `Idempotency-Key` з іншим тілом запиту — помилка `422`.
- Якщо перший запит ще виконується, повтор отримає `409` — спробуйте за мить.

Якщо ключ видано з позначкою «Зміни — лише з моїм підтвердженням», зміна не виконується одразу: API відповідає `202` і `plan_id`, а людина підтверджує план у кабінеті в розділі «Плани».

## Формат відповідей і помилок

Списки віддаються сторінками: `{"data": [...], "next": "…"}`. Щоб отримати наступну сторінку, передайте `next` як параметр `after`; `limit` — до 500, за замовчуванням 100.

Помилка завжди має однакову форму:

```json
{ "error": { "code": "right_missing", "message": { "uk": "…", "en": "…" } } }
```

`code` стабільний — на нього можна спиратися в коді; текст у `message` може змінюватися.

| Код | HTTP | Що означає |
| --- | --- | --- |
| `key_required` | 401 | немає заголовка `Authorization: Bearer zr_…` |
| `key_invalid` | 401 | це не ключ ZRAZU або в ньому помилка |
| `key_unknown` | 401 | ключ не знайдено |
| `key_revoked`, `key_expired`, `key_idle` | 401 | ключ відкликано, строк минув або його не викликали 90 днів |
| `key_in_query` | 400 | ключ передано в адресі запиту |
| `ip_not_allowed` | 403 | ключ не працює з цієї IP-адреси |
| `right_missing` | 403 | у ключа немає потрібного права |
| `out_of_scope` | 403 | ім'я поза доменами ключа |
| `not_found` | 404 | зону чи сертифікат не знайдено |
| `idempotency_key_required` | 400 | немає заголовка `Idempotency-Key` |
| `idempotency_key_reused` | 422 | `Idempotency-Key` уже використано з іншим запитом |
| `rate_limited` | 429 | забагато викликів; заголовок `Retry-After` — через скільки секунд повторити |

## Ліміти

| Що | Ліміт |
| --- | --- |
| Один ключ | 120 викликів на хвилину і у 25 разів більше за годину |
| Одна IP-адреса | 240 викликів на хвилину |
| Змінювальні виклики організації | 1000 на добу — всі ключі разом |

Для окремих організацій ліміт на хвилину може бути іншим. Відповідь `429` містить `Retry-After`: почекайте стільки секунд і повторіть запит з тим самим `Idempotency-Key`.

## Якщо не вийшло

- **`401 key_required`.** Додайте заголовок `Authorization: Bearer zr_live_…` — саме `Bearer` і пробіл перед ключем.
- **`401 key_unknown` або `key_invalid`.** Перевірте, чи ключ скопійовано повністю, без пробілу в кінці. Якщо ключ загубили, випустіть новий: показати старий не можна.
- **`403 right_missing`.** Ключ не має потрібного права. Відкрийте `GET /v1/api-keys/current`, перегляньте `permissions`, за потреби випустіть новий ключ з потрібним правом.
- **`403 ip_not_allowed`.** Для ключа задано список IP-адрес, а запит прийшов з іншої. Додайте адресу в кабінеті або випустіть новий ключ.
- **`429 rate_limited`.** Зменште частоту запитів і дотримуйтесь `Retry-After`.
- **`400 idempotency_key_required`.** Додайте заголовок `Idempotency-Key` до запиту, що змінює дані.

Ціни на послуги — на сторінці [цін](https://zrazu.com/prices/).