DNS Records

List Records

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

Query Parameters:

Parameter	Type	Description
`page`	int	Page number (default: 1)
`per_page`	int	Items per page (default: 20, max: 100)
`type`	string	Filter: `A`, `AAAA`, `CNAME`, `MX`, `TXT`, `PTR`, `SRV`, `NS`, `SSHFP`, `TLSA`
`name`	string	Filter by name (case-insensitive substring)
`content`	string	Filter by content (case-insensitive substring)

Get Single Record

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

Create A Record

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

Create AAAA Record

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}'

Create CNAME Record

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 Exclusivity (RFC 1033): A CNAME cannot coexist with any other record type at the same name. Attempting to create a CNAME when other records exist at that name — or vice versa — returns error 1005.

Create MX Record

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}'

For MX records, priority is required and content is the mail exchange hostname.

Create TXT Record

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"}'

Create SRV Record

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"
    }
  }'

For SRV records, use the data object with priority, weight, port, and target.

Create PTR Record

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"}'

Create SSHFP Record

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}'

Format (RFC 4255): content is "<algorithm> <fingerprint type> <hex digest>":

Field	Values
Algorithm	`1` RSA, `2` DSS, `3` ECDSA, `4` Ed25519
Fingerprint type	`1` SHA-1 (40 hex chars), `2` SHA-256 (64 hex chars)

Generate the fingerprint from a public key:

# SHA-1 (fingerprint type 1)
ssh-keygen -lf /path/to/id_ed25519.pub

# SHA-256 (fingerprint type 2)
ssh-keygen -E sha256 -lf /path/to/id_ed25519.pub

The digest is the hex part of the output (after the key size and ECDSA/ED25519/RSA label). An invalid format returns error 1007.

Create TLSA Record

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}'

Format (RFC 6698): content is "<usage> <selector> <matching type> <hex certificate data>":

Field	Values
Usage	`0` PKIX, `1` DANE-EE, `2` PKIX-TEE, `3` DANE-EE-TEE
Selector	`0` full certificate, `1` subject public key information (SPKI)
Matching type	`0` exact (DER, even-length hex), `1` SHA-256 (64 hex chars), `2` SHA-384 (96 hex chars)

DANE service names (RFC 7218, RFC 8406, RFC 7671, RFC 7672): _443._tcp (HTTPS), _25._tcp (SMTP), _submission._tcp / _imap._tcp / _pop3._tcp (mail), _563._tcp (NNTP). RFC 8406 recommends usage 3 (DANE-EE-TEE) for HTTPS.

Generate the certificate data for 1 1 1 (DANE-EE, SPKI, SHA-256) from a certificate:

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

-pubin is required: the pipe carries the public key extracted from the certificate, while openssl pkey without it expects a private key (the .key file is not needed to generate TLSA data).

For 0 0 0 (full certificate, exact match) use the DER of the whole certificate: openssl x509 -in cert.pem -outform der | xxd -p -c 200 | tr -d '\n'. An invalid format returns error 1007. TLSA works without DNSSEC for the PKIX profiles (0/2); DANE profiles (1/3) are verified by resolvers only in signed zones.

Create Record with Address Group

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}'

When address_group_id is set, the record resolves to all healthy members of the group (with load balancing).

IXFR Guard: When IXFR is enabled for a zone, records cannot be bound to address groups (error 1019). IXFR and address groups are mutually exclusive. To use address groups, first disable IXFR via PATCH /zones/{id} with "ixfr_enabled": false.

Full Update Record (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}'

Requires all fields. Replaces the entire record.

Partial Update Record (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"}'

Only provided fields are updated. Other fields retain their current values.

Delete Record

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 Locked: NS records at zone apex are system-managed and cannot be modified, deleted, or toggled (error 1008).

Record Response Fields

Field	Type	Description
`id`	string	UUID (uuidv7)
`type`	string	`A`, `AAAA`, `CNAME`, `MX`, `TXT`, `PTR`, `SRV`, `NS`, `SSHFP`, `TLSA`
`name`	string	FQDN
`content`	string	Record data (IP, hostname, etc.)
`ttl`	int	TTL in seconds
`locked`	boolean	`true` for NS at apex (protected from deletion)
`zone_id`	int	Zone ID
`zone_name`	string	Zone domain name
`created_on`	string	ISO 8601 timestamp
`modified_on`	string	ISO 8601 timestamp
`data`	object/null	Structured data for SRV: `{priority, weight, port, target}`
`priority`	int/null	MX preference or SRV priority

Batch Record Operations

Atomic, all-or-nothing record changes with idempotency support.

Batch Create/Update/Delete

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

Actions:

Action	Description
`CREATE`	Create record. Fails if already exists
`DELETE`	Delete record by `id`
`UPSERT`	Create or update by `name` + `type`

IXFR Guard in Batch: Batch operations that attempt to bind address groups to records in an IXFR-enabled zone will fail validation with error 1019. The entire batch is rejected — no partial changes are applied.

Response:

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

Idempotency

Include an Idempotency-Key header to safely retry requests. The key is valid for 7 days. Re-sending the same key returns the cached response.

Batch Validation Error

If any change in the batch is invalid, no changes are applied:

{
  "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": []
}

Last updated: 2026-06-26