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