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