DNS записи

Список записей

curl -s "https://api.1bytedns.ru/client/v1/zones/42/dns_records?type=A&page=1&per_page=50" \
  -H "Authorization: Bearer TOKEN" | python3 -m json.tool

Параметры запроса:

Параметр	Тип	Описание
`page`	int	Номер страницы (по умолчанию: 1)
`per_page`	int	Записей на странице (по умолчанию: 20, макс: 100)
`type`	string	Фильтр: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `PTR`, `SRV`, `NS`
`name`	string	Фильтр по имени (без учёта регистра)
`content`	string	Фильтр по содержанию (без учёта регистра)

Получение одной записи

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

Создание записи A

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}' | python3 -m json.tool

Создание записи AAAA

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": "AAAA", "name": "www.example.com", "content": "2001:db8::1", "ttl": 3600}'

Создание записи CNAME

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": "CNAME", "name": "blog.example.com", "content": "www.example.com"}'

Эксклюзивность CNAME (RFC 1033): CNAME не может сосуществовать с любым другим типом записи с тем же именем. Попытка создать CNAME, когда другие записи уже существуют с этим именем (или наоборот), возвращает ошибку 1005.

Создание записи MX

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": "MX", "name": "example.com", "content": "mail.example.com", "priority": 10, "ttl": 3600}'

Для записей MX поле priority обязательно, а content — это имя почтового сервера.

Создание записи TXT

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": "TXT", "name": "example.com", "content": "v=spf1 include:_spf.google.com ~all"}'

Создание записи SRV

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": "SRV",
    "name": "_sip._tcp.example.com",
    "ttl": 3600,
    "data": {
      "priority": 10,
      "weight": 5,
      "port": 5060,
      "target": "sipserver.example.com"
    }
  }'

Для записей SRV используйте объект data с полями priority, weight, port и target.

Создание записи PTR

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": "PTR", "name": "1.2.0.192.in-addr.arpa", "content": "host.example.com"}'

Создание записи с группой адресов

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": "app.example.com", "address_group_id": 5}'

Когда задан address_group_id, запись разрешается во все здоровые члены группы (с балансировкой нагрузки).

IXFR Guard: Когда IXFR включён для зоны, записи нельзя привязывать к группам адресов (ошибка 1019). IXFR и группы адресов взаимно исключают друг друга. Для использования групп адресов сначала отключите IXFR через PATCH /zones/{id} с "ixfr_enabled": false.

Полное обновление записи (PUT)

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

Требует все поля. Заменяет всю запись.

Частичное обновление записи (PATCH)

curl -s -X PATCH https://api.1bytedns.ru/client/v1/zones/42/dns_records/01arz31vyVk8v8YqQk0YFD8v79 \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "192.0.2.3"}'

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

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

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

NS apex заблокирован: NS-записи на вершине зоны управляются системой и не могут быть изменены, удалены или отключены (ошибка 1008).

Поля ответа записи

Поле	Тип	Описание
`id`	string	UUID (uuidv7)
`type`	string	`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `PTR`, `SRV`, `NS`
`name`	string	FQDN
`content`	string	Данные записи (IP, hostname и т.д.)
`ttl`	int	TTL в секундах
`locked`	boolean	`true` для NS на вершине (защита от удаления)
`zone_id`	int	ID зоны
`zone_name`	string	Доменное имя зоны
`created_on`	string	Метка времени ISO 8601
`modified_on`	string	Метка времени ISO 8601
`data`	object/null	Структурированные данные для SRV: `{priority, weight, port, target}`
`priority`	int/null	Приоритет MX или SRV

Пакетные операции с записями

Атомарные, all-or-nothing изменения записей с поддержкой идемпотентности.

Пакетное создание/обновление/удаление

curl -s -X POST https://api.1bytedns.ru/client/v1/zones/42/dns_records/batch \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-request-id-12345" \
  -d '{
    "comment": "Deploy production DNS",
    "changes": [
      {
        "action": "CREATE",
        "record": {
          "type": "A",
          "name": "www.example.com",
          "content": "192.0.2.1",
          "ttl": 300
        }
      },
      {
        "action": "DELETE",
        "record": {
          "id": "01arz31vyVk8v8YqQk0YFD8v79"
        }
      },
      {
        "action": "UPSERT",
        "record": {
          "type": "A",
          "name": "api.example.com",
          "content": "192.0.2.100",
          "ttl": 60
        }
      }
    ]
  }' | python3 -m json.tool

Действия:

Действие	Описание
`CREATE`	Создать запись. Ошибка, если уже существует
`DELETE`	Удалить запись по `id`
`UPSERT`	Создать или обновить по `name` + `type`

IXFR Guard в batch: Пакетные операции, которые пытаются привязать группы адресов к записям в зоне с включённым IXFR, будут отклонены с ошибкой 1019. Весь batch отклоняется — частичные изменения не применяются.

Ответ:

{
  "success": true,
  "result": {
    "id": "batch-667f1a2b3c4d5",
    "status": "completed",
    "submitted_on": "2024-06-23T12:00:00Z",
    "serial": 2024062302,
    "changes_applied": 3
  },
  "errors": [],
  "messages": []
}

Идемпотентность

Используйте заголовок Idempotency-Key для безопасных повторов запросов. Ключ действителен 7 дней. Повторная отправка с тем же ключом возвращает кэшированный ответ.

Ошибка валидации batch

Если любое изменение в batch невалидно, никакие изменения не применяются:

{
  "success": false,
  "result": null,
  "errors": [
    {"code": 1012, "message": "Batch contains 1 error(s) — no changes applied"},
    {"code": 1005, "message": "CNAME 'www' cannot coexist with existing A record", "change_index": 0}
  ],
  "messages": []
}

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