Skip to main content

Zone Management

A DNS zone represents a domain and all its subdomains. This guide covers creating, listing, updating, and deleting zones.

Creating a Zone​

Endpoint​

POST /v1/dns/zones

Request​

curl -X POST https://api.wayscloud.services/v1/dns/zones \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "dnssec_enabled": true,
    "default_ttl": 3600
  }'

Parameters:

FieldTypeRequiredDescription
domainstringYesDomain name (e.g., "example.com")
dnssec_enabledbooleanNoEnable DNSSEC (default: true)
default_ttlintegerNoDefault TTL for records (default: 3600)

Response​

{
  "zone_id": "zone_abc123",
  "domain": "example.com",
  "status": "pending",
  "dnssec_enabled": true,
  "default_ttl": 3600,
  "nameservers": [
    "grieg.wayscloud.no",
    "lindgren.wayscloud.se",
    "aalto.wayscloud.fi",
    "bohr.wayscloud.dk"
  ],
  "created_at": "2025-11-03T18:00:00Z",
  "updated_at": "2025-11-03T18:00:00Z"
}

Fields:

  • zone_id - Unique zone identifier (use this for API operations)
  • domain - Domain name
  • status - Zone status: pending, active, error
  • dnssec_enabled - Whether DNSSEC is enabled
  • default_ttl - Default TTL for new records
  • nameservers - WAYSCloud nameservers for this zone
  • created_at - Zone creation timestamp
  • updated_at - Last update timestamp

Next Steps After Creation​

  1. Update your domain registrar to use WAYSCloud nameservers:

    grieg.wayscloud.no
    lindgren.wayscloud.se
    aalto.wayscloud.fi
    bohr.wayscloud.dk

  2. Wait for DNS propagation (usually 24-48 hours)

  3. Add DNS records to your zone

  4. (Optional) Enable DNSSEC at your registrar if enabled

Listing Zones​

Endpoint​

GET /v1/dns/zones

Request​

curl -X GET https://api.wayscloud.services/v1/dns/zones \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY"

Response​

{
  "zones": [
    {
      "zone_id": "zone_abc123",
      "domain": "example.com",
      "status": "active",
      "dnssec_enabled": true,
      "record_count": 15,
      "created_at": "2025-11-03T18:00:00Z"
    },
    {
      "zone_id": "zone_def456",
      "domain": "another-domain.com",
      "status": "active",
      "dnssec_enabled": false,
      "record_count": 8,
      "created_at": "2025-11-02T14:30:00Z"
    }
  ],
  "total": 2
}

Getting Zone Details​

Endpoint​

GET /v1/dns/zones/{zone_id}

Request​

curl -X GET https://api.wayscloud.services/v1/dns/zones/zone_abc123 \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY"

Response​

{
  "zone_id": "zone_abc123",
  "domain": "example.com",
  "status": "active",
  "dnssec_enabled": true,
  "default_ttl": 3600,
  "nameservers": [
    "grieg.wayscloud.no",
    "lindgren.wayscloud.se",
    "aalto.wayscloud.fi",
    "bohr.wayscloud.dk"
  ],
  "record_count": 15,
  "created_at": "2025-11-03T18:00:00Z",
  "updated_at": "2025-11-04T10:15:00Z",
  "ds_records": [
    {
      "key_tag": 12345,
      "algorithm": 13,
      "digest_type": 2,
      "digest": "abc123def456..."
    }
  ]
}

Updating a Zone​

Endpoint​

PUT /v1/dns/zones/{zone_id}

Request​

curl -X PUT https://api.wayscloud.services/v1/dns/zones/zone_abc123 \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_ttl": 7200
  }'

Updatable Fields:

  • default_ttl - Default TTL for new records
info

DNSSEC settings cannot be changed via this endpoint. Use the DNSSEC endpoints instead.

Response​

{
  "zone_id": "zone_abc123",
  "domain": "example.com",
  "status": "active",
  "dnssec_enabled": true,
  "default_ttl": 7200,
  "nameservers": [...],
  "updated_at": "2025-11-04T12:00:00Z"
}

Deleting a Zone​

Endpoint​

DELETE /v1/dns/zones/{zone_id}

Request​

curl -X DELETE https://api.wayscloud.services/v1/dns/zones/zone_abc123 \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY"

Response​

{
  "success": true,
  "message": "Zone deleted successfully",
  "zone_id": "zone_abc123"
}
Warning

Deleting a zone is permanent and cannot be undone. All DNS records in the zone will be deleted.

Zone Status​

Zones can have the following statuses:

StatusDescription
pendingZone created, waiting for nameserver delegation
activeZone is active and serving DNS queries
errorZone configuration error (contact support)
suspendedZone temporarily suspended (billing issue)
deletingZone deletion in progress

Nameservers​

All WAYSCloud zones use these nameservers:

grieg.wayscloud.no     # Norway - IPv4 + IPv6
lindgren.wayscloud.se  # Sweden - IPv4 + IPv6
aalto.wayscloud.fi     # Finland - IPv4 + IPv6
bohr.wayscloud.dk      # Denmark - IPv4 + IPv6
tip

Configure all four nameservers at your registrar for maximum redundancy.

Error Codes​

CodeDescriptionResolution
ZONE_NOT_FOUNDZone doesn't existVerify zone_id
ZONE_ALREADY_EXISTSDomain already has a zoneUse existing zone or delete first
INVALID_DOMAINInvalid domain formatCheck domain name format
QUOTA_EXCEEDEDMaximum zones reachedDelete unused zones or upgrade plan

Best Practices​

Domain Validation​

Ensure domains are valid before creating zones:

import re

def is_valid_domain(domain):
    """Validate domain name format"""
    pattern = r'^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,}$'
    return re.match(pattern, domain.lower()) is not None

# Usage
if is_valid_domain('example.com'):
    create_zone('example.com')

Check Zone Status​

Always check zone status before adding records:

def wait_for_zone_active(zone_id, max_wait=300):
    """Wait for zone to become active"""
    import time

    start = time.time()
    while time.time() - start < max_wait:
        zone = api.get_zone(zone_id)
        if zone['status'] == 'active':
            return True
        time.sleep(10)

    raise TimeoutError("Zone did not become active")

List Zones with Filtering​

Filter zones by domain name:

zones = api.list_zones()
my_zones = [z for z in zones['zones'] if 'example' in z['domain']]

Next Steps​