05 API

05 · API

Базовый URL: https://<хост>/<префикс>/api/v1/. Машиночитаемая спецификация — /api/v1/openapi.yaml.

Аутентификация

Способ	Заголовки	Для кого
Bearer	Authorization: Bearer rg_…	интеграции, cron, AI-агент
Cookie-сессия	cookie rg_session + X-CSRF-Token	веб-интерфейс

CSRF-токен выдаёт GET /api/v1/bootstrap. Bearer-запросы CSRF не требуют.

Scopes

read → write → dns:write; отдельно secrets:read, admin, regru:raw.

Scope	Что разрешает
read	инвентарь, баланс, журналы
write	продление, автопродление, синхронизация, доступы
dns:write	DNS-записи и SOA
secrets:read	расшифровка паролей (каждое чтение — в журнал)
admin	токены, настройки, очистка зоны, сертификат
regru:raw	произвольные команды REG.RU API

Формат

Успех:

{ "data": { }, "meta": { "total": 68, "page": 1, "per_page": 50 } }

Ошибка:

{
  "error": { "code": "VALIDATION_FAILED", "message": "…", "details": { } },
  "request_id": "8d65ccf249db974a"
}

request_id = заголовок X-Request-Id = строка в журнале.

Локализация

• Accept-Language: de-DE,de;q=0.9 — язык ответа (en, ru, zh, hi, de, es); по умолчанию en.
• GET /api/v1/locales — список языков.
• POST /api/v1/locale {"locale":"es"} — сохранить выбор в cookie.
• Коды ошибок стабильны и не зависят от языка.

Эндпоинты

Система

Метод	Путь	Право	Описание
GET	/health	—	статус, версия, PHP, БД
GET	/bootstrap	опционально	актор, CSRF, enum'ы, локаль
GET	/locales	—	список языков
POST	/locale	—	сохранить язык
POST	/auth/login	—	вход
POST	/auth/logout	сессия	выход
GET	/auth/me	любое	текущий актор
POST	/auth/password	сессия	смена пароля
GET	/dashboard	read	агрегаты обзора
GET	/inventory	read	инвентарь без секретов
GET	/audit	admin	журнал

Домены и DNS

Метод	Путь	Право
GET	/domains	read
GET	/domains/{name}	read
POST	/domains/{name}/renew	write
POST	/domains/{name}/autorenew	write
PUT	/domains/{name}/ns	write
POST	/domains/{name}/refresh	read
POST	/domains/{name}/certificate	admin
GET/POST	/domains/{name}/dnssec	read / admin
GET	/domains/{name}/dns	read
POST/PUT/DELETE	/domains/{name}/dns/records	dns:write
PUT	/domains/{name}/dns/soa	dns:write
POST	/domains/{name}/dns/clear	admin

Типы записей: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA. Для SRV content — "<вес> <порт> <цель>"; для CAA — "[flags] <tag> <value>".

Хостинги, доступы, биллинг

Метод	Путь	Право
GET	/hostings	read
GET	/hostings/{id}	read
POST	/hostings/sync	write
POST	/hostings/{id}/reveal	secrets:read
GET/POST/PUT/DELETE	/credentials…	read/write
POST	/credentials/{id}/reveal	secrets:read
POST	/credentials/generate	write
GET	/billing, /billing/unpaid, /billing/bills	read
GET/POST	/sync	read / write
GET/POST	/tokens	admin
DELETE	/tokens/{id}	admin
GET	/meta, /meta/commands, /meta/prices	read
POST	/regru/call	regru:raw

Примеры

# инвентарь
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://example.com/regru/api/v1/inventory" | jq

# DNS-запись
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subname":"api","rectype":"A","content":"203.0.113.10"}' \
  "https://example.com/regru/api/v1/domains/example.com/dns/records"

# любая команда REG.RU
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"user/get_balance","input":{}}' \
  "https://example.com/regru/api/v1/regru/call"

Лимиты

• Вход: 10 попыток на аккаунт за 15 минут + лимит по IP.
• API панели: 600 запросов в минуту на токен/IP.
• Исходящие REG.RU: локальный предохранитель 1100/час; официально 1200/час.
• Ошибка лимита — 429 с Retry-After.

Дальше: MCP · Неполадки