Skip to main content

Record Management

Manage DNS records within your zones. This guide covers CRUD operations for DNS records.

Creating Records​

Endpoint​

POST /v1/dns/zones/{zone_id}/records

Request​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

Parameters:

FieldTypeRequiredDescription
typestringYesRecord type (A, AAAA, CNAME, MX, TXT, SRV, CAA)
namestringYesRecord name (use "@" for root domain)
valuestringYesRecord value (format depends on type)
ttlintegerNoTime to live in seconds (default: zone default)
priorityintegerNoPriority (required for MX, SRV records)

Response​

{
  "record_id": "rec_001",
  "type": "A",
  "name": "www",
  "value": "192.0.2.1",
  "ttl": 3600,
  "zone_id": "zone_abc123",
  "created_at": "2025-11-04T10:00:00Z",
  "updated_at": "2025-11-04T10:00:00Z"
}

Listing Records​

Endpoint​

GET /v1/dns/zones/{zone_id}/records

Request​

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

Query Parameters:

ParameterTypeDescription
typestringFilter by record type (e.g., ?type=A)
namestringFilter by record name (e.g., ?name=www)

Response​

{
  "zone_id": "zone_abc123",
  "domain": "example.com",
  "records": [
    {
      "record_id": "rec_001",
      "type": "A",
      "name": "www",
      "value": "192.0.2.1",
      "ttl": 3600,
      "created_at": "2025-11-03T18:05:00Z"
    },
    {
      "record_id": "rec_002",
      "type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "priority": 10,
      "ttl": 3600,
      "created_at": "2025-11-03T18:06:00Z"
    }
  ],
  "total_records": 2
}

Getting a Record​

Endpoint​

GET /v1/dns/zones/{zone_id}/records/{record_id}

Request​

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

Response​

{
  "record_id": "rec_001",
  "type": "A",
  "name": "www",
  "value": "192.0.2.1",
  "ttl": 3600,
  "zone_id": "zone_abc123",
  "created_at": "2025-11-03T18:05:00Z",
  "updated_at": "2025-11-03T18:05:00Z"
}

Updating a Record​

Endpoint​

PUT /v1/dns/zones/{zone_id}/records/{record_id}

Request​

curl -X PUT https://api.wayscloud.services/v1/dns/zones/zone_abc123/records/rec_001 \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "192.0.2.100",
    "ttl": 300
  }'

Updatable Fields:

  • value - New record value
  • ttl - New TTL value
  • priority - New priority (MX/SRV records only)
info

You cannot change the record type or name. Delete and recreate the record instead.

Response​

{
  "record_id": "rec_001",
  "type": "A",
  "name": "www",
  "value": "192.0.2.100",
  "ttl": 300,
  "updated_at": "2025-11-04T12:00:00Z"
}

Deleting a Record​

Endpoint​

DELETE /v1/dns/zones/{zone_id}/records/{record_id}

Request​

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

Response​

{
  "success": true,
  "message": "Record deleted successfully",
  "record_id": "rec_001"
}

Quick Examples​

A Record (IPv4)​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

AAAA Record (IPv6)​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AAAA",
    "name": "www",
    "value": "2001:db8::1",
    "ttl": 3600
  }'

CNAME Record (Alias)​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CNAME",
    "name": "blog",
    "value": "myblog.hosted.com",
    "ttl": 3600
  }'

MX Record (Mail Server)​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "priority": 10,
    "ttl": 3600
  }'

TXT Record​

curl -X POST https://api.wayscloud.services/v1/dns/zones/zone_abc123/records \
  -H "Authorization: Bearer wayscloud_dns_prod_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TXT",
    "name": "@",
    "value": "v=spf1 include:_spf.google.com ~all",
    "ttl": 3600
  }'

Error Codes​

CodeDescriptionResolution
ZONE_NOT_FOUNDZone doesn't existVerify zone_id
RECORD_NOT_FOUNDRecord doesn't existCheck record_id
INVALID_RECORD_TYPEUnsupported record typeUse A, AAAA, CNAME, MX, TXT, SRV, CAA
INVALID_VALUERecord value format invalidCheck value format for record type
DUPLICATE_RECORDRecord already existsUpdate existing record or use different name
CNAME_CONFLICTCNAME conflicts with other recordsCNAME cannot coexist with other record types

DNS Propagation​

DNS changes propagate at different speeds:

Immediate (0-60 seconds):

  • Changes visible on WAYSCloud nameservers immediately

Normal Propagation (based on TTL):

  • TTL=300: Propagate within 5-10 minutes
  • TTL=3600: Propagate within 1-2 hours
  • TTL=86400: May take up to 48 hours

Checking Propagation​

# Check specific nameserver
dig @grieg.wayscloud.no example.com

# Check your local resolver
dig example.com

# Check Google's public DNS
dig @8.8.8.8 example.com

Best Practices​

1. Use Appropriate TTLs​

# Before making DNS changes
record.update(ttl=300)  # Lower TTL for quick rollback
time.sleep(3600)  # Wait for old TTL to expire

# Make the actual change
record.update(value='192.0.2.100')

# After changes are stable
time.sleep(600)  # Monitor for 10 minutes
record.update(ttl=3600)  # Restore normal TTL

2. Validate Before Creating​

import ipaddress

def validate_a_record(value):
    """Validate IPv4 address"""
    try:
        ipaddress.IPv4Address(value)
        return True
    except ValueError:
        return False

def validate_aaaa_record(value):
    """Validate IPv6 address"""
    try:
        ipaddress.IPv6Address(value)
        return True
    except ValueError:
        return False

# Usage
if validate_a_record('192.0.2.1'):
    api.create_record(zone_id, 'A', 'www', '192.0.2.1')

3. Handle Conflicts​

def create_or_update_record(zone_id, record_type, name, value, ttl=3600):
    """Create record or update if exists"""
    try:
        # Try to create
        return api.create_record(zone_id, record_type, name, value, ttl)
    except DuplicateRecordError as e:
        # Record exists, get and update it
        existing = api.get_record_by_name(zone_id, name)
        return api.update_record(zone_id, existing['record_id'], value=value, ttl=ttl)

4. Use Filters When Listing​

# Get only A records
a_records = api.list_records(zone_id, type='A')

# Get specific subdomain records
www_records = api.list_records(zone_id, name='www')

Next Steps​