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...

Thathamisa Libaka Tsohle tsa DNS

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

Liparamitha tsa Potso

Kopo ea Mohlala

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);

Karabo ea Mohlala

[
  {
    "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

Likhoutu tsa Boemo ba Karabelo

Get DNS Zone Details

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

Liparamitha tsa Tsela

Karabo ea Mohlala

{
  "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"
    }
  ]
}

Likhoutu tsa Boemo ba Karabelo

Create DNS Zone

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

Kopa Liparamente tsa 'Mele

Kopo ea Mohlala

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);

Karabo ea Mohlala

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

Likhoutu tsa Boemo ba Karabelo

Delete DNS Zone

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

Liparamitha tsa Tsela

Likhoutu tsa Boemo ba Karabelo

List DNS Records in Zone

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

Liparamitha tsa Tsela

Kopo ea Mohlala

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

Karabo ea Mohlala

[
  {
    "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).

Kopa Liparamente tsa 'Mele

Kopo ea Mohlala

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())

Likhoutu tsa Boemo ba Karabelo

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