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`, `SSHFP`, `TLSA`
`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"}'

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

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": "SSHFP", "name": "ssh.example.com", "content": "4 2 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "ttl": 3600}'

Формат (RFC 4255): content — это "<алгоритм> <тип отпечатка> <hex-дайджест>":

Поле	Значения
Алгоритм	`1` RSA, `2` DSS, `3` ECDSA, `4` Ed25519
Тип отпечатка	`1` SHA-1 (40 hex-символов), `2` SHA-256 (64 hex-символа)

Сгенерировать отпечаток из публичного ключа:

# SHA-1 (тип отпечатка 1)
ssh-keygen -lf /path/to/id_ed25519.pub

# SHA-256 (тип отпечатка 2)
ssh-keygen -E sha256 -lf /path/to/id_ed25519.pub

Дайджест — это hex-часть вывода (после размера ключа и метки ECDSA/ED25519/RSA). Неверный формат возвращает ошибку 1007.

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

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": "TLSA", "name": "_443._tcp.example.com", "content": "3 1 1 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "ttl": 3600}'

Формат (RFC 6698): content — это "<usage> <selector> <matching type> <hex-данные сертификата>":

Поле	Значения
Usage	`0` PKIX, `1` DANE-EE, `2` PKIX-TEE, `3` DANE-EE-TEE
Selector	`0` полный сертификат, `1` subject public key information (SPKI)
Matching type	`0` точное (DER, hex чётной длины), `1` SHA-256 (64 hex-символа), `2` SHA-384 (96 hex-символов)

Имена DANE-сервисов (RFC 7218, RFC 8406, RFC 7671, RFC 7672): _443._tcp (HTTPS), _25._tcp (SMTP), _submission._tcp / _imap._tcp / _pop3._tcp (почта), _563._tcp (NNTP). RFC 8406 рекомендует usage 3 (DANE-EE-TEE) для HTTPS.

Сгенерировать данные сертификата для 1 1 1 (DANE-EE, SPKI, SHA-256) из сертификата:

openssl x509 -in cert.pem -pubkey -noout \
  | openssl pkey -pubin -pubout -outform der \
  | openssl dgst -sha256 -binary \
  | xxd -p -c 64

-pubin обязателен: в конвейере идёт открытый ключ из сертификата, а openssl pkey без него ожидает закрытый (сам .key для генерации TLSA не нужен).

Для 0 0 0 (полный сертификат, точное совпадение) используйте DER всего сертификата: openssl x509 -in cert.pem -outform der | xxd -p -c 200 | tr -d '\n'. Неверный формат возвращает ошибку 1007. TLSA работает без DNSSEC для PKIX-профилей (0/2); DANE-профили (1/3) резолвер проверяет только в подписанных зонах.

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

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`, `SSHFP`, `TLSA`
`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