Overview

Zones are the primary containers for DNS records. Each zone represents a domain (like example.com) and contains all the DNS records for that domain and its subdomains.

Required scopes: zones:read, zones:write

Endpoints

Method	Endpoint	Description
`POST`	`/v1/zones`	Create a new zone
`GET`	`/v1/zones`	List all zones
`GET`	`/v1/zones/{zone_id}`	Get zone details
`PUT`	`/v1/zones/{zone_id}`	Update a zone
`DELETE`	`/v1/zones/{zone_id}`	Delete a zone
`GET`	`/v1/zones/{zone_id}/usage`	Get zone usage statistics

Create a Zone

Create a new primary DNS zone:

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

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Domain name (e.g., `example.com`)
`type`	string	No	Zone type: `primary` (default)
`region`	string	No	Deployment region
`ttl`	integer	No	Default TTL in seconds (default: 3600)

Available Regions:

Region	Description
`EU_GLOBAL`	European Union plus Global anycast ASNs
`EU`	European Union anycast ASN only
`GLOBAL`	Global anycast ASN only

When region is omitted, DNScale uses the default region configured for your customer account.

Response:

{
  "status": "success",
  "data": {
    "id": "zone_abc123",
    "name": "example.com",
    "type": "primary",
    "region": "EU_GLOBAL",
    "ttl": 3600,
    "status": "active",
    "dnssec_enabled": false,
    "nameservers": [
      "ns1.dnscale.eu",
      "ns1.dnscale.com",
      "ns2.dnscale.eu",
      "ns2.dnscale.com"
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

List Zones

Retrieve all zones for your account:

curl "https://api.dnscale.eu/v1/zones?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters:

Parameter	Default	Description
`limit`	10	Number of zones per page (max: 100)
`offset`	0	Number of zones to skip

Response:

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "zone_abc123",
        "name": "example.com",
        "type": "primary",
        "status": "active",
        "record_count": 15,
        "dnssec_enabled": true
      },
      {
        "id": "zone_def456",
        "name": "example.org",
        "type": "primary",
        "status": "active",
        "record_count": 8,
        "dnssec_enabled": false
      }
    ],
    "total": 2,
    "limit": 20,
    "offset": 0
  }
}

Get Zone Details

Retrieve detailed information about a specific zone:

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

The response includes DNSSEC status and assigned nameservers.

Update a Zone

Update zone settings:

curl -X PUT https://api.dnscale.eu/v1/zones/{zone_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": 900,
    "status": "active"
  }'

Updatable Fields:

Field	Type	Description
`ttl`	integer	Default TTL for new records
`status`	string	Zone status: `active`, `disabled`

Delete a Zone

Delete a zone and all its records:

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

Response:

{
  "status": "success",
  "data": {
    "message": "Zone deletion initiated"
  }
}

Deletion is Permanent

Zone deletion removes all DNS records and is irreversible. The API responds with 202 Accepted and processes deletion asynchronously.

Get Zone Usage

Retrieve query statistics for a specific zone:

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

Required scope: usage:read

Response:

{
  "status": "success",
  "data": {
    "zone_id": "zone_abc123",
    "zone_name": "example.com",
    "period": "current_month",
    "queries": 125000,
    "queries_by_type": {
      "A": 80000,
      "AAAA": 25000,
      "MX": 10000,
      "TXT": 10000
    }
  }
}

DNSSEC Management

DNSSEC endpoints are nested under zones. See DNSSEC documentation for details.

Method	Endpoint	Description
`GET`	`/v1/zones/{zone_id}/dnssec/status`	Get DNSSEC status
`PATCH`	`/v1/zones/{zone_id}/dnssec/status`	Enable/disable DNSSEC
`GET`	`/v1/zones/{zone_id}/dnssec/cryptokeys`	List cryptographic keys
`GET`	`/v1/zones/{zone_id}/dnssec/ds`	Get DS records for registrar

Example: Complete Zone Setup

Create a zone and add essential records:

# 1. Create the zone
ZONE_ID=$(curl -s -X POST https://api.dnscale.eu/v1/zones \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "example.com"}' | jq -r '.data.id')
 
# 2. Add A record for apex
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}'
 
# 3. Add A record for www
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}'
 
# 4. Add MX records
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}'
 
# 5. Enable DNSSEC
curl -X PATCH https://api.dnscale.eu/v1/zones/$ZONE_ID/dnssec/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'