API і MCP

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

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

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

Окремо є MCP для ШІ-агентів: він відкритий, без ключа, але лише читає й показує паспорт публічного домену.

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

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

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

Що доступно саме вашому ключу, залежить від його прав: див. ключі API.

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

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

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

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.

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.

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

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

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

КодHTTPЩо означає
key_required401немає заголовка Authorization: Bearer zr_…
key_invalid401це не ключ ZRAZU або в ньому помилка
key_unknown401ключ не знайдено
key_revoked, key_expired, key_idle401ключ відкликано, строк минув або його не викликали 90 днів
key_in_query400ключ передано в адресі запиту
ip_not_allowed403ключ не працює з цієї IP-адреси
right_missing403у ключа немає потрібного права
out_of_scope403ім'я поза доменами ключа
not_found404зону чи сертифікат не знайдено
idempotency_key_required400немає заголовка Idempotency-Key
idempotency_key_reused422Idempotency-Key уже використано з іншим запитом
rate_limited429забагато викликів; заголовок 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 до запиту, що змінює дані.

Ціни на послуги — на сторінці цін.

Ця сторінка в Markdown