DNS Management API

Overview

The DNS API provides full management of DNS zones and records. All zones are hosted on VPS.org's authoritative nameservers with automatic BIND9 zone file generation and deployment.

Nameserver Infrastructure

• ns1.vps.org (38.248.6.195) - Primary master with DNSSEC inline-signing
• ns2.vps.org (38.248.6.196) - Secondary slave
• ns3.vps.org (38.248.6.197) - Secondary slave

Key Features

• Automatic BIND9 zone file generation and deployment
• Zone transfers via TSIG authentication (master-slave replication)
• Support for all major DNS record types (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
• Domain name filtering and UUID-based zone identification
• Nested routes for zone-specific record management

Authentication

All DNS API requests require Bearer token authentication. Generate API tokens from your account dashboard at /account/developers/ with the following permissions:

• dns:list - View DNS zones and records
• dns:create - Create new zones and records
• dns:update - Modify existing zones and records
• dns:delete - Delete zones and records
• dns:* - Full DNS management access

Example

Authorization: Bearer vps_abc123def456...

Rārangihia ngā Rohe DNS Katoa

Retrieve a paginated list of all DNS zones owned by the authenticated user. Supports filtering by domain name.

Ngā Tawhā Uiui

Tauira Tono

curl -X GET "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

const zones = await response.json();
console.log(zones);

Tauira Whakautu

[
  {
    "uuid": "abc123-def456-ghi789",
    "domain": "example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "record_count": 12
  },
  {
    "uuid": "xyz789-uvw456-rst123",
    "domain": "myapp.io",
    "created_at": "2024-06-20T14:15:00Z",
    "record_count": 8
  }
]

Response Fields

Ngā Waehere Tūnga Urupare

Get DNS Zone Details

Retrieve detailed information about a specific DNS zone, including all records.

Ngā Tawhā Ara

Tauira Whakautu

{
  "uuid": "abc123-def456-ghi789",
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "record_count": 5,
  "records": [
    {
      "uuid": "rec-001",
      "record_type": "A",
      "name": "@",
      "value": "192.0.2.1",
      "ttl": 3600,
      "priority": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "rec-002",
      "record_type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2024-01-15T10:32:00Z"
    }
  ]
}

Ngā Waehere Tūnga Urupare

Create DNS Zone

Create a new DNS zone for a domain. The zone will be immediately deployed to VPS.org nameservers.

Tonohia ngā Tawhā Tinana

Tauira Tono

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "newdomain.com"}'

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {"domain": "newdomain.com"}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({domain: 'newdomain.com'})
});

const zone = await response.json();
console.log(zone);

Tauira Whakautu

{
  "uuid": "new-zone-uuid",
  "domain": "newdomain.com",
  "created_at": "2026-01-18T16:45:00Z",
  "record_count": 0,
  "records": []
}

Ngā Waehere Tūnga Urupare

Delete DNS Zone

Permanently delete a DNS zone and all associated records. This action cannot be undone.

Ngā Tawhā Ara

Ngā Waehere Tūnga Urupare

List DNS Records in Zone

Retrieve all DNS records for a specific zone (nested route).

Ngā Tawhā Ara

Tauira Tono

curl -X GET "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Tauira Whakautu

[
  {
    "uuid": "rec-001",
    "record_type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "uuid": "rec-002",
    "record_type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "ttl": 3600,
    "priority": 10,
    "created_at": "2024-01-15T10:32:00Z"
  }
]

Create DNS Record in Zone

Add a new DNS record to a specific zone (nested route).

Tonohia ngā Tawhā Tinana

Tauira Tono

curl -X POST "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

import requests

url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Ngā Waehere Tūnga Urupare

Manage DNS Records (Direct Access)

Full CRUD operations on individual DNS records using record UUID.

Available Operations

• GET /api/v1/dns-records/{uuid}/ - Retrieve record details
• PUT /api/v1/dns-records/{uuid}/ - Full update (all fields required)
• PATCH /api/v1/dns-records/{uuid}/ - Partial update (only changed fields)
• DELETE /api/v1/dns-records/{uuid}/ - Delete record

Query Parameters (for GET /api/v1/dns-records/)

Example: Update TTL of a Record

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/{rec-uuid}/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 1800}'

Supported DNS Record Types

Best Practices

TTL Configuration

• Production (stable): 3600-86400 seconds (1-24 hours)
• Before migration: 300-600 seconds (5-10 minutes) - Lower TTL before planned changes
• Development: 300-1800 seconds (5-30 minutes) for faster testing

Common Patterns

• Root domain (@): Use A/AAAA records, not CNAME
• www subdomain: Can use CNAME pointing to root or separate A record
• Email (MX): Always include priority, lower number = higher priority
• CNAME: Cannot coexist with other record types for same name

Security

• CAA Records: Specify which CAs can issue certificates
• SPF/DKIM/DMARC: Configure email authentication to prevent spoofing
• Regular Audits: Review DNS records quarterly, remove unused entries

Error Handling

Common Errors

Example Error Response

{
  "detail": "MX records require a priority value",
  "error_code": "validation_error",
  "field": "priority"
}

Testing DNS Changes

Verify Record Propagation

# Query A record
dig example.com A

# Query specific nameserver
dig @ns1.vps.org example.com

# Query MX records
dig example.com MX

# Check all records
dig example.com ANY

Using Online Tools

• whatsmydns.net: Check global DNS propagation
• dnschecker.org: Multi-location DNS lookup
• mxtoolbox.com: Email-related DNS testing