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

Important: API tokens are shown only once during creation. Store them securely. If you lose a token, you must generate a new one.

얻다 /api/v1/dns-zones/

모든 DNS 영역 나열

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

쿼리 매개변수

매개변수	유형	필수의	설명
`domain`	string	아니요	Filter zones by exact domain name (e.g., `example.com`)

예시 요청

cURL

Python

JavaScript

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

Field	유형	설명
`uuid`	string	Unique zone identifier (used in API requests)
`domain`	string	Domain name for this DNS zone
`created_at`	datetime	Zone creation timestamp (ISO 8601 format)
`record_count`	integer	Total number of DNS records in this zone

응답 상태 코드

200	Successfully retrieved DNS zones list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Token lacks `dns:list` permission

얻다 /api/v1/dns-zones/{uuid}/

Get DNS Zone Details

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

경로 매개변수

매개변수	유형	필수의	설명
`uuid`	string	예	Unique zone identifier

예시 답변

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

응답 상태 코드

200	Successfully retrieved zone details
404	Zone not found or not owned by user

우편 /api/v1/dns-zones/

Create DNS Zone

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

요청 본문 매개변수

매개변수	유형	필수의	설명
`domain`	string	예	Domain name (e.g., `example.com`)

예시 요청

cURL

Python

JavaScript

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": []
}

응답 상태 코드

201	DNS zone created successfully
400	Bad Request - Invalid domain name or zone already exists
403	Forbidden - Token lacks `dns:create` permission

삭제 /api/v1/dns-zones/{uuid}/

Delete DNS Zone

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

경로 매개변수

매개변수	유형	필수의	설명
`uuid`	string	예	Unique zone identifier

응답 상태 코드

204	Zone deleted successfully (no response body)
403	Forbidden - Token lacks `dns:delete` permission
404	Zone not found

얻다 /api/v1/dns-zones/{uuid}/records/

List DNS Records in Zone

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

경로 매개변수

매개변수	유형	필수의	설명
`uuid`	string	예	Zone UUID

예시 요청

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

우편 /api/v1/dns-zones/{uuid}/records/

Create DNS Record in Zone

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

요청 본문 매개변수

매개변수	유형	필수의	설명
`record_type`	string	예	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	예	Record name (`@` for root, subdomain, or FQDN)
`value`	string	예	Record value (IP address, hostname, text)
`ttl`	integer	No	Time to live in seconds (default: 3600)
`priority`	integer	For MX/SRV	Priority (required for MX and SRV records)

예시 요청

cURL

Python

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

응답 상태 코드

201	DNS record created successfully
400	Bad Request - Invalid parameters or validation error (e.g., MX record missing priority)

GET PUT PATCH DELETE /api/v1/dns-records/{uuid}/

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

Parameter	유형	설명
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

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

유형	Purpose	Example Value	Priority Required
A	Maps domain to IPv4 address	192.0.2.1	아니요
AAAA	Maps domain to IPv6 address	2001:0db8::1	아니요
CNAME	Creates alias to another domain	example.com	아니요
MX	Mail server for domain	mail.example.com	예
TXT	Text record (SPF, DKIM, verification)	v=spf1 include:_spf.google.com ~all	아니요
NS	Nameserver delegation	ns1.example.com	아니요
SRV	Service location record	10 5060 sip.example.com	예
CAA	Certificate authority authorization	0 issue "letsencrypt.org"	아니요

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

Status Code	Error	Solution
400	Invalid domain name	Ensure domain follows DNS naming conventions
400	MX record requires priority	Include `priority` field for MX and SRV records
401	Invalid API token	Check token format (must start with `vps_`)
403	Missing permission	Generate new token with required `dns:*` permissions
404	Zone/record not found	Verify UUID and ensure resource belongs to your account

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

VPS.org API

DNS Management API

Overview

Nameserver Infrastructure

Key Features

Authentication

Example

모든 DNS 영역 나열

쿼리 매개변수

예시 요청

예시 답변

Response Fields

응답 상태 코드

Get DNS Zone Details

경로 매개변수

예시 답변

응답 상태 코드

Create DNS Zone

요청 본문 매개변수

예시 요청

예시 답변

응답 상태 코드

Delete DNS Zone

경로 매개변수

응답 상태 코드

List DNS Records in Zone

경로 매개변수

예시 요청

예시 답변

Create DNS Record in Zone

요청 본문 매개변수

예시 요청

응답 상태 코드

Manage DNS Records (Direct Access)

Available Operations

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

Example: Update TTL of a Record

Supported DNS Record Types

Best Practices

TTL Configuration

Common Patterns

Security

Error Handling

Common Errors

Example Error Response

Testing DNS Changes

Verify Record Propagation

Using Online Tools