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`
`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 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`
`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