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

د ټولو DNS زونونو لیست وکړئ

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

د پوښتنې پیرامیټرې

د غوښتنې بېلګه

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

د ځواب بېلګه

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

د غبرګون حالت کوډونه

Get DNS Zone Details

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

د لارې پیرامیټرې

د ځواب بېلګه

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

د غبرګون حالت کوډونه

Create DNS Zone

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

د بدن پیرامیټرو غوښتنه وکړئ

د غوښتنې بېلګه

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

د ځواب بېلګه

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

د غبرګون حالت کوډونه

Delete DNS Zone

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

د لارې پیرامیټرې

د غبرګون حالت کوډونه

List DNS Records in Zone

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

د لارې پیرامیټرې

د غوښتنې بېلګه

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

د ځواب بېلګه

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

د بدن پیرامیټرو غوښتنه وکړئ

د غوښتنې بېلګه

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

د غبرګون حالت کوډونه

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