Зоны

Список зон

curl -s "https://api.1bytedns.ru/client/v1/zones?page=1&per_page=20&name=example" \
  -H "Authorization: Bearer TOKEN" | python3 -m json.tool

Параметры запроса: page, per_page, name (фильтр поиска)

{
  "success": true,
  "result": [
    {
      "id": 42,
      "name": "example.com",
      "record_count": 15,
      "labels": {"env": "production", "team": "backend"},
      "enabled": true,
      "verification_status": "active",
      "ixfr_enabled": false,
      "name_servers": ["ns1.dnsprovider.local", "ns2.dnsprovider.local", "ns3.dnsprovider.local"],
      "created_on": "2024-01-15T12:00:00Z",
      "modified_on": "2024-06-01T10:30:00Z"
    }
  ],
  "result_info": {"page": 1, "per_page": 20, "count": 1, "total_count": 3, "total_pages": 1},
  "errors": [],
  "messages": []
}

Детали зоны

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

{
  "success": true,
  "result": {
    "id": 42,
    "name": "example.com",
    "labels": {"env": "production", "team": "backend"},
    "enabled": true,
    "verification_status": "active",
    "default_ttl": 3600,
    "soa_mname": "ns1.dnsprovider.local",
    "soa_rname": "admin.example.com",
    "soa_serial": 2024062301,
    "soa_serial_auto": true,
    "soa_refresh": 7200,
    "soa_retry": 900,
    "soa_expire": 1209600,
    "soa_minimum": 86400,
    "transfer_enabled": false,
    "ixfr_enabled": false,
    "name_servers": ["ns1.dnsprovider.local", "ns2.dnsprovider.local", "ns3.dnsprovider.local"],
    "record_count": 15,
    "created_on": "2024-01-15T12:00:00Z",
    "modified_on": "2024-06-01T10:30:00Z"
  },
  "errors": [],
  "messages": []
}

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

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,
    "soa_serial_auto": true,
    "soa_refresh": 7200,
    "soa_retry": 900,
    "soa_expire": 1209600,
    "soa_minimum": 86400
  }' | python3 -m json.tool

Параметры тела:

Поле	Тип	Обяз.	По умолчанию	Описание
`name`	string	Да	—	Доменное имя
`default_ttl`	int	Нет	86400	TTL по умолчанию в секундах
`soa_mname`	string	Нет	`ns1.1bytedns.ru`	Основной NS-сервер
`soa_rname`	string	Нет	`admin.{name}`	Email администратора SOA
`soa_serial_auto`	boolean	Нет	true	Авто-инкремент serial при изменениях
`soa_refresh`	int	Нет	7200	Интервал refresh SOA
`soa_retry`	int	Нет	900	Интервал retry SOA
`soa_expire`	int	Нет	1209600	Срок истечения SOA
`soa_minimum`	int	Нет	86400	Минимальный TTL SOA
`labels`	object	Нет	`{}`	Метки key-value (макс 64). Ключ: `[a-z0-9_-]`, макс 63 символа. Значение: `[a-z0-9_.-]`, макс 63 символа.

При создании API автоматически:

Валидирует доменное имя
Проверяет уникальность в рамках пользователя (у одного пользователя не может быть двух зон с одинаковым именем)
Проверяет лимит зон пользователя (макс 300)
Определяет формат NS: если нет активной зоны с таким именем, используются стандартные NS (ns1/2/3.1bytedns.ru); иначе user-specific NS ({userId}.ns1/2/3.1bytedns.ru)
Создаёт зону в базе данных
Назначает 3 NS-сервера и связывает пользователя с зоной
Создаёт NS записи на вершине зоны
Устанавливает verification_status: active для стандартных NS, pending для user-specific NS

Обновление зоны

curl -s -X PATCH https://api.1bytedns.ru/client/v1/zones/42 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "default_ttl": 300,
    "soa_serial_auto": false,
    "transfer_enabled": true,
    "enabled": false,
    "labels": {"env": "staging"}
  }' | python3 -m json.tool

Параметры тела:

Поле	Тип	Описание
`default_ttl`	int	TTL по умолчанию в секундах
`soa_rname`	string	Email администратора SOA
`soa_serial_auto`	boolean	Авто-инкремент serial при изменениях
`soa_refresh`	int	Интервал refresh SOA
`soa_retry`	int	Интервал retry SOA
`soa_expire`	int	Срок истечения SOA
`soa_minimum`	int	Минимальный TTL SOA
`transfer_enabled`	boolean	Включить/отключить AXFR/IXFR передачу зоны
`enabled`	boolean	Включить/отключить зону. При повторном включении, если существует другая зона с тем же именем, `verification_status` становится `pending`
`labels`	object	Полная замена меток зоны
`ixfr_enabled`	boolean	Включить/отключить IXFR (инкрементальную передачу зоны). Требует `transfer_enabled=true`. Нельзя включить, когда записи привязаны к группам адресов (ошибка 1018). Отключение `transfer_enabled` автоматически отключает IXFR.

Обновляются только переданные поля. Возвращает полные детали зоны.

Удаление зоны

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

Зона должна быть пуста (остаются только автоматически созданные NS записи). Ошибка 1009 если в зоне есть пользовательские записи.

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

Метки зон (Labels)

Метки — пары key-value, хранящиеся как JSONB. Максимум 64 метки на зону. Ключ: [a-z0-9_-] (макс 63 символа). Значение: [a-z0-9_.-] (макс 63 символа). Зарезервированный префикс dns_ нельзя использовать для ключей.

Получить метки зоны

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

{
  "success": true,
  "result": {
    "env": "production",
    "team": "backend"
  },
  "errors": [],
  "messages": []
}

Обновить метки зоны (полная замена)

curl -s -X PATCH https://api.1bytedns.ru/client/v1/zones/42/labels \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels": {"env": "staging", "team": "frontend"}}' | python3 -m json.tool

Переданные метки полностью заменяют существующие. Для удаления метки — не включать её в запрос. Для очистки всех — {"labels": {}}.

Получить все метки пользователя

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

{
  "success": true,
  "result": {
    "keys": ["env", "team"],
    "values": {
      "env": ["production", "staging"],
      "team": ["backend", "frontend"]
    }
  },
  "errors": [],
  "messages": []
}

Zone Transfer ACL

Управление разрешёнными IP для AXFR/IXFR передачи зоны.

Список Transfer ACL

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

{
  "success": true,
  "result": [
    {"id": 1, "allowed_ip": "192.0.2.1", "created_on": "2024-01-15T12:00:00Z"}
  ],
  "errors": [],
  "messages": []
}

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

curl -s -X POST https://api.1bytedns.ru/client/v1/zones/42/transfer_acl \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"allowed_ip": "198.51.100.1"}' | python3 -m json.tool

Удаление записи ACL

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

Обновлено: 2026-06-26