Обзор API

Базовый URL: https://api.1bytedns.ru/client/v1

Все эндпоинты возвращают JSON-ответы. Каждый ответ содержит поле success.

Быстрый старт

Создание API токена

API токены можно создавать только через веб-интерфейс. Войдите в аккаунт, перейдите в API Токены и создайте новый токен с нужным именем, правами, scope и сроком действия.

Важно: Полное значение токена показывается только один раз при создании. Сохраните его надёжно.

Список ваших зон

curl -s https://api.1bytedns.ru/client/v1/zones \
  -H "Authorization: Bearer abc123def456ghi789jkl012mno345pqr678stu901vwx234" | python3 -m json.tool

Создание зоны

curl -s -X POST https://api.1bytedns.ru/client/v1/zones \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com", "default_ttl": 3600}'

Добавление DNS записи

curl -s -X POST https://api.1bytedns.ru/client/v1/zones/42/dns_records \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "A", "name": "www.example.com", "content": "192.0.2.1", "ttl": 3600}'

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

Все запросы к API требуют Bearer токен в заголовке Authorization:

Authorization: Bearer <api_token>

Разрешения

Разрешение	Описание
zones:read	GET зоны
zones:edit	POST/PATCH/DELETE зоны
records:read	GET записи
records:edit	POST/PATCH/DELETE записи
groups:read	GET группы адресов
groups:edit	POST/PATCH/DELETE группы адресов
health:read	GET статус здоровья
health:edit	PATCH настройки здоровья

Scope токена (опционально)

Токены можно ограничить конкретными зонами (scope_zone_ids) или записями (scope_record_ids). Если scope задан, запросы вне scope возвращают 403.

Неудачная аутентификация

{
  "success": false,
  "result": null,
  "errors": [
    {"code": 1011, "message": "Missing Authorization header"}
  ],
  "messages": []
}

Формат ответов

Успех

{
  "success": true,
  "result": { ... },
  "errors": [],
  "messages": []
}

Ошибка

{
  "success": false,
  "result": null,
  "errors": [
    {"code": 1001, "message": "Zone not found"}
  ],
  "messages": []
}

Пагинация

{
  "success": true,
  "result": [ ... ],
  "result_info": {
    "page": 1,
    "per_page": 20,
    "count": 5,
    "total_count": 42,
    "total_pages": 3
  },
  "errors": [],
  "messages": []
}

Успех с предупреждениями

{
  "success": true,
  "result": { ... },
  "errors": [],
  "messages": [
    {"code": 20001, "message": "Example informational message", "type": "warn"}
  ]
}

Rate Limiting

Эндпоинт	Лимит	Окно
Все (глобальный)	1200 запросов	60 секунд
Batch операции	60 запросов	60 секунд
Создание зон	30 запросов	60 секунд

Каждый ответ включает заголовки rate limit:

X-RateLimit-Limit: 1200
X-RateLimit-Remaining: 1195
X-RateLimit-Reset: 1705312860

При превышении API возвращает HTTP 429:

{
  "success": false,
  "result": null,
  "errors": [{"code": 1010, "message": "Rate limit exceeded"}],
  "messages": []
}

Коды ошибок

Код	HTTP	Описание
1000	400	Bad Request — ошибка валидации
1001	404	Ресурс не найден (зона, запись, токен)
1002	403	Доступ запрещён — ресурс не принадлежит пользователю
1003	409	У пользователя уже есть зона с таким именем (уникальность в рамках пользователя)
1004	400	Неверное доменное имя
1005	400	Конфликт CNAME — не может сосуществовать с другими типами
1006	404	Запись не найдена
1007	400	Неверные данные записи
1008	400	NS apex заблокирован — системные записи нельзя изменять
1009	400	Зона не пуста — нельзя удалить
1010	429	Превышен лимит запросов
1011	401	Неверный или истёкший API токен
1012	400/422	Неверный batch изменений
1013	404	Группа адресов не найдена
1014	400	Член или группа уже существуют
1015	400	Неверный IP-адрес
1016	400	Достигнут лимит зон (300)
1017	409	IXFR требует сначала включить передачу зоны
1018	409	Нельзя включить IXFR: в зоне есть записи, привязанные к группам адресов
1019	409	Нельзя привязать группу адресов: IXFR включён для этой зоны