Overview

DNS records define how your domain responds to queries. DNScale supports all standard record types plus modern types like HTTPS and SVCB.

Required scopes: zones:read + records:read (read), zones:read + records:write (write).

Record routes are nested under /v1/zones/{zone_id}/records, so every record operation also requires zones:read to look up the parent zone. A key with only records:* will return 403.

Shared RRset Comments

Records can include an optional private comment of up to 500 characters. Comments are stored as PowerDNS RRset metadata and are not published through DNS.

An RRset contains every value with the same name and type. This means that multiple A values for www, for example, all share one comment. Changing the comment through any one of those values changes it for the entire RRset.

Endpoints

Endpoint reference

Method	Endpoint	Description
`POST`	`/v1/zones/{zone_id}/records`	Create a record
`GET`	`/v1/zones/{zone_id}/records`	List all records
`GET`	`/v1/zones/{zone_id}/records/{record_id}`	Get a record
`PUT`	`/v1/zones/{zone_id}/records/{record_id}`	Update a record
`PUT`	`/v1/zones/{zone_id}/records/by-name/{name}/{type}`	Update by name/type
`DELETE`	`/v1/zones/{zone_id}/records/{record_id}`	Delete a record
`DELETE`	`/v1/zones/{zone_id}/records/by-name/{name}/{type}`	Delete by name/type

Supported Record Types

DNScale supports 14 record types:

Type	Description	Documentation
A	IPv4 address	A Record Guide
AAAA	IPv6 address	AAAA Record Guide
CNAME	Canonical name (alias)	CNAME Guide
MX	Mail exchange	MX Record Guide
TXT	Text data (SPF, DKIM, etc.)	TXT Record Guide
NS	Nameserver delegation	NS Record Guide
SRV	Service location	SRV Record Guide
PTR	Reverse DNS	PTR Record Guide
CAA	Certificate authority authorization	CAA Record Guide
TLSA	TLS certificate association (DANE)	TLSA Record Guide
SSHFP	SSH fingerprint	SSHFP Record Guide
HTTPS	HTTPS service binding	HTTPS Record Guide
SVCB	General service binding	SVCB Record Guide
ALIAS	CNAME-like at apex	ALIAS Record Guide

Create a Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "www",
    "type": "A",
    "content": "192.0.2.1",
    "ttl": 3600,
    "comment": "Production web endpoints"
  }'

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Record name (`@` for apex, or subdomain)
`type`	string	Yes	Record type (A, AAAA, CNAME, etc.)
`content`	string	Yes	Record value
`ttl`	integer	No	Time to live in seconds (default: 3600, minimum: 300, maximum: 86400)
`disabled`	boolean	No	Whether record is disabled (default: false)
`comment`	string	No	Private RRset comment, shared by all values with the same name/type (maximum: 500 characters)

When adding another value to an existing RRset, omit comment to preserve the current shared comment. Supplying a comment replaces it for every value in that RRset.

Response:

{
  "status": "success",
  "data": {
    "message": "Record created successfully",
    "record": {
      "id": "rec_abc123",
      "name": "www.example.com.",
      "type": "A",
      "content": "192.0.2.1",
      "ttl": 3600,
      "disabled": false,
      "comment": "Production web endpoints"
    }
  }
}

Record Type Examples

A Record (IPv4)

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "A",
    "content": "192.0.2.1",
    "ttl": 3600
  }'

AAAA Record (IPv6)

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "AAAA",
    "content": "2001:db8::1",
    "ttl": 3600
  }'

CNAME Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "www",
    "type": "CNAME",
    "content": "example.com",
    "ttl": 3600
  }'

MX Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "MX",
    "content": "10 mail.example.com",
    "ttl": 3600
  }'

TXT Record (SPF)

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "TXT",
    "content": "v=spf1 include:_spf.google.com ~all",
    "ttl": 3600
  }'

SRV Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "_sip._tcp",
    "type": "SRV",
    "content": "10 5 5060 sip.example.com",
    "ttl": 3600
  }'

CAA Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "CAA",
    "content": "0 issue \"letsencrypt.org\"",
    "ttl": 3600
  }'

HTTPS Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "HTTPS",
    "content": "1 . alpn=\"h3,h2\"",
    "ttl": 3600
  }'

ALIAS Record

curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "@",
    "type": "ALIAS",
    "content": "myapp.herokuapp.com",
    "ttl": 3600
  }'

List Records

Retrieve all records in a zone:

curl "https://api.dnscale.eu/v1/zones/{zone_id}/records?limit=1000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Default	Description
`limit`	50	Records per page (max: 1000)
`offset`	0	Records to skip

Response:

{
  "status": "success",
  "data": {
    "records": [
      {
        "id": "rec_abc123",
        "name": "example.com.",
        "type": "A",
        "content": "192.0.2.1",
        "ttl": 3600
      },
      {
        "id": "rec_def456",
        "name": "www.example.com.",
        "type": "CNAME",
        "content": "example.com.",
        "ttl": 3600
      }
    ],
    "pagination": {
      "total": 10001,
      "offset": 0,
      "limit": 1000,
      "count": 1000,
      "has_more": true
    }
  }
}

Get a Record

curl https://api.dnscale.eu/v1/zones/{zone_id}/records/{record_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a Record

By Record ID

curl -X PUT https://api.dnscale.eu/v1/zones/{zone_id}/records/{record_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "www",
    "type": "A",
    "content": "192.0.2.2",
    "ttl": 300
  }'

The name and type in the body must match the record_id; mismatches return 400.

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Record name (must match record_id)
`type`	string	Yes	Record type (must match record_id)
`content`	string	Yes	New record value
`ttl`	integer	Yes	New TTL in seconds (minimum: 300, maximum: 86400)
`disabled`	boolean	No	Enable/disable the record
`comment`	string	No	Replace the shared RRset comment (maximum: 500 characters); omit to preserve or send an empty string to remove it

Note: Record IDs are derived from name, type, and content, so updating content returns a record with a new ID. To update a record without tracking its ID, use the by-name endpoint below.

By Name and Type

Useful when you want to rotate a record's content without first looking up its ID:

curl -X PUT "https://api.dnscale.eu/v1/zones/{zone_id}/records/by-name/www/A" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "192.0.2.2",
    "ttl": 300
  }'

For multi-value record types (A, AAAA, MX, NS, TXT, SRV, CAA, TLSA, SSHFP, HTTPS, SVCB), append ?content= to identify which value to update:

curl -X PUT "https://api.dnscale.eu/v1/zones/{zone_id}/records/by-name/www/A?content=192.0.2.1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "192.0.2.5",
    "ttl": 300
  }'

Request Body:

Field	Type	Required	Description
`content`	string	Yes	New record value
`ttl`	integer	Yes	New TTL in seconds (minimum: 300, maximum: 86400)
`disabled`	boolean	No	Enable/disable the record
`comment`	string	No	Replace the shared RRset comment (maximum: 500 characters); omit to preserve or send an empty string to remove it

Delete a Record

By Record ID

curl -X DELETE https://api.dnscale.eu/v1/zones/{zone_id}/records/{record_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

By Name and Type

Useful for deleting records when you know the name and type but not the ID:

curl -X DELETE "https://api.dnscale.eu/v1/zones/{zone_id}/records/by-name/_acme-challenge/TXT" \
  -H "Authorization: Bearer YOUR_API_KEY"

For multi-value records, append ?content= to delete a specific value:

curl -X DELETE "https://api.dnscale.eu/v1/zones/{zone_id}/records/by-name/www/A?content=192.0.2.1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Multi-Value Records

Some record types support multiple values (e.g., multiple A records for round-robin):

# Add first A record
curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "content": "192.0.2.1", "ttl": 300}'
 
# Add second A record (same name, same type)
curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "www", "type": "A", "content": "192.0.2.2", "ttl": 300}'

Multi-value record types: A, AAAA, MX, NS, TXT, SRV, CAA, TLSA, SSHFP, HTTPS, SVCB

Single-value record types: CNAME, ALIAS

ACME DNS-01 Challenge Example

Automate Let's Encrypt certificate validation:

# Create challenge record
curl -X POST https://api.dnscale.eu/v1/zones/{zone_id}/records \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "_acme-challenge",
    "type": "TXT",
    "content": "validation-token-from-acme-server",
    "ttl": 300
  }'
 
# After validation, clean up
curl -X DELETE "https://api.dnscale.eu/v1/zones/{zone_id}/records/by-name/_acme-challenge/TXT" \
  -H "Authorization: Bearer YOUR_API_KEY"

Common Errors

Error	Cause	Solution
`record_already_exists`	Duplicate single-value record	Delete existing record first
`invalid_record_content`	Malformed record value	Check content format for the record type
`invalid_record_ttl`	TTL below 300 or above 86400 seconds	Use a TTL between 300 and 86400 seconds
`cname_conflict`	CNAME with other records at same name	CNAME must be the only record at a name
`zone_not_found`	Invalid zone ID	Verify zone exists and you have access