VPS.org API

Tài liệu API REST

API quản lý DNS

Tạo vùng DNS và quản lý các ghi chép của nó. Các vùng được phục vụ bởi ns1. vps.org, ns2. vps.org và ns3. vps.org.

Điểm cuối 13
Đường cơ sở /api/v1/dns-zones, /api/v1/dns-records

Tổng quan

Một vùng chứa các ghi chép cho một miền. Mỗi thay đổi bạn thực hiện thông qua API sẽ được đẩy ngay lập tức đến máy phục vụ tên VPS.org. Để phục vụ một miền từ các vùng này, hãy đặt máy phục vụ tên của nó tại cơ quan đăng ký của bạn là ns1. vps.org, ns2. vps.org và ns3. vps.org.

Các thay đổi được lưu và công bố trong một bước: nếu máy phục vụ tên từ chối thay đổi, yêu cầu trả về 502 và không có gì được lưu. Không thể tạo vùng cho một miền mà tài khoản khác đã quản lý, vùng cha hay con của tài khoản khác, hoặc tên được bảo lưu VPS.org.

Cần quyền: dns:list (GET), dns:create (POST), dns:update (PUT, PATCH, sync), dns:delete (DELETE), dns:*

LẤY /api/v1/dns-zones/

Liệt kê tất cả các vùng DNS

Trả lại các vùng của bạn, mới nhất trước, 25 trên mỗi trang. Các ghi chép không được bao gồm ở đây; lấy một vùng đơn để lấy chúng.

Tham số truy vấn

Tham số Kiểu Yêu cầu Mô tả
domain string Không Chỉ trả lại vùng có tên miền này
page integer Không Số trang, bắt đầu từ 1

Ví dụ về yêu cầu

cURL
Python
JavaScript
curl -X GET "https://admin.vps.org/api/v1/dns-zones/?domain=example.com" \
  -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, params={"domain": "example.com"})
for zone in response.json()["results"]:
    print(zone["uuid"], zone["domain"], zone["record_count"])
const response = await fetch('https://admin.vps.org/api/v1/dns-zones/?domain=example.com', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

Ví dụ về câu trả lời

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c",
      "domain": "example.com",
      "created_at": "2026-09-06T03:11:48.829693Z",
      "record_count": 5
    }
  ]
}

Các trường phản hồi

Địa điểm Kiểu Mô tả
uuid string Định danh vùng
domain string Tên miền, lưu bằng chữ thường
created_at datetime Thời gian tạo (ISO 8601, UTC)
record_count integer Số lượng ghi chép trong vùng, bao gồm ba ghi chép NS

Mã trạng thái phản hồi

200 Thành công
403 Thiếu hoặc không hợp lệ token API, hoặc token không có quyền cần thiết
POST /api/v1/dns-zones/

Tạo khu vực DNS

Tạo một vùng và công bố nó. Khu vực bắt đầu với ba ghi chú NS cho ns1, ns2 và ns3. vps.org, là ghi chú hệ thống và không thể sửa hay xoá.

Các tham số thân yêu cầu

Tham số Kiểu Yêu cầu Mô tả
domain string Đúng Tên miền, ví dụ example. com 
curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com"}'

Ví dụ về câu trả lời

{
  "uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c",
  "domain": "example.com",
  "created_at": "2026-09-14T21:02:11.402113Z",
  "records": [
    {
      "uuid": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
      "record_type": "NS",
      "name": "@",
      "value": "ns1.vps.org",
      "ttl": 86400,
      "priority": null,
      "created_at": "2026-09-14"
    },
    ...
  ],
  "record_count": 3
}

Mã trạng thái phản hồi

201 Khu vực được tạo
400 Tên miền thiếu hoặc không hợp lệ
LẤY /api/v1/dns-zones/{uuid}/

Lấy chi tiết khu vực DNS

Trả lại một vùng với tất cả các ghi chép của nó trong một ma trận ghi chép. Sự đáp ứng có cùng hình dạng như sự đáp ứng tạo ở trên.

curl -X GET "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Mã trạng thái phản hồi

200 Thành công
404 Không tìm thấy, hoặc nó thuộc về tài khoản khác
XÓA BỎ /api/v1/dns-zones/{uuid}/

Xoá vùng DNS

Gỡ bỏ vùng từ cả ba máy phục vụ tên, kiểm tra xem không có máy nào phục vụ nó, rồi xoá vùng và các ghi chép của nó. Nếu máy phục vụ tên vẫn đáp ứng cho vùng, yêu cầu thất bại và vùng được giữ lại để bạn có thể thử lại.

curl -X DELETE "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Mã trạng thái phản hồi

204 Đã xóa.
400 Một máy phục vụ tên vẫn phục vụ vùng này. Khu vực không bị xoá; trường chi tiết liệt kê các lỗi.
404 Không tìm thấy, hoặc nó thuộc về tài khoản khác
LẤY POST /api/v1/dns-zones/{uuid}/records/

Danh sách hoặc thêm ghi chép trong vùng

GET trả về tất cả các ghi chép trong vùng như một ma trận đơn giản (không có trang), sắp xếp theo kiểu và tên. POST thêm một ghi chép vào vùng và công bố nó.

Các tham số thân yêu cầu (POST)

Tham số Kiểu Yêu cầu Mô tả
record_type string Đúng A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
name string Đúng @ cho chính miền, hoặc một nhãn như www. Tên được lưu bằng chữ thường.
value string Đúng Dữ liệu ghi, ví dụ địa chỉ IP hay tên máy. Tên máy không cần dấu chấm cuối và giá trị TXT không cần dấu ngoặc kép; cả hai đều được thêm khi ghi được công bố.
ttl integer Đúng Thời gian sống trong giây
priority integer Chỉ MX và SRV Cần thiết cho các ghi chú MX và SRV và bỏ qua cho các kiểu khác. Đối với SRV, đặt trọng lượng, cổng và mục tiêu vào giá trị.

Ví dụ về yêu cầu

cURL
Python
curl -X POST "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"record_type": "MX", "name": "@", "value": "mail.example.com", "ttl": 3600, "priority": 10}'
import requests

zone_uuid = "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c"
url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {"record_type": "A", "name": "www", "value": "203.0.113.10", "ttl": 3600}

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

Ví dụ về câu trả lời

{
  "uuid": "9d430082-5562-42b4-a0b2-12a6f6c862f9",
  "record_type": "MX",
  "name": "@",
  "value": "mail.example.com",
  "ttl": 3600,
  "priority": 10,
  "created_at": "2026-09-14"
}

Các trường phản hồi

Địa điểm Kiểu Mô tả
uuid string Định danh ghi chép, được dùng bởi /api/v1/dns-records/endpoints
priority integer | null Ưu tiên cho các ghi chú MX và SRV, nếu không thì rỗng
created_at date Chỉ ngày tạo (Y- MM- DD), không có thời gian

Mã trạng thái phản hồi

200 GET: hồ sơ của vùng
201 Đã tạo
400 Lỗi xác thực, ví dụ như kiểu ghi chép không biết, thiếu ttl, hay ghi chép MX hay SRV không có ưu tiên
404 Không tìm thấy, hoặc nó thuộc về tài khoản khác
POST /api/v1/dns-zones/{uuid}/sync/

Công bố lại vùng

Đẩy vùng và tất cả các ghi chép của nó lại vào máy phục vụ tên. Các thay đổi ghi chép được công bố tự động, nhưng công bố là nỗ lực tốt nhất và thất bại không làm thất bại yêu cầu ban đầu, vì vậy dùng điều này khi thay đổi không xuất hiện trong tìm kiếm DNS. Không cần thiết phải có cơ thể yêu cầu.

curl -X POST "https://admin.vps.org/api/v1/dns-zones/c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c/sync/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "detail": "Zone example.com synced to PowerDNS"
}
LẤY POST /api/v1/dns-records/

Danh sách hoặc tạo ghi chép giữa các vùng

GET trả về các ghi chép của tất cả các vùng của bạn, 25 trên mỗi trang, sắp xếp theo miền, kiểu và tên. POST tạo ra một ghi chép giống như điểm cuối của ghi chép vùng, nhưng lấy vùng trong cơ thể là zone_ uuid.

Tham số truy vấn

Tham số Kiểu Yêu cầu Mô tả
zone string Không Chỉ ghi chép của vùng với uuid này
record_type string Không Chỉ ghi chép kiểu này, ví dụ MX (không phân biệt chữ cái)
page integer Không Số trang, bắt đầu từ 1 
curl -X GET "https://admin.vps.org/api/v1/dns-records/?zone=c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c&record_type=A" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -X POST "https://admin.vps.org/api/v1/dns-records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone_uuid": "c7a1e3f0-2b4d-4e6a-9c8b-0d1f2e3a4b5c", "record_type": "TXT", "name": "@", "value": "v=spf1 mx -all", "ttl": 3600}'
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "4b8e2c10-7d3f-4a5b-9e6c-1a2b3c4d5e6f",
      "record_type": "A",
      "name": "www",
      "value": "203.0.113.10",
      "ttl": 3600,
      "priority": null,
      "created_at": "2026-09-14"
    }
  ]
}

Mã trạng thái phản hồi

200 GET: thành công
201 Đã tạo
400 Lỗi xác thực, hoặc zone_ uuid thiếu hoặc không phải là một trong các vùng của bạn
LẤY PUT PATCH XÓA BỎ /api/v1/dns-records/{uuid}/

Nhập, cập nhật hoặc xóa một ghi chú

GET trả về một ghi chú. PUT thay thế nó và cần record_ type, name, value và ttl. PATCH chỉ thay đổi các trường bạn gửi. DELETE gỡ bỏ ghi chú và trả lại 204 không có cơ thể. Các thay đổi được công bố ngay lập tức. Các ghi chú NS được tạo với vùng là ghi chú hệ thống: cập nhật hoặc xóa chúng sẽ trả lại 403.

Khi bạn PATCH ưu tiên của một MX hoặc SRV ghi, gửi record_type trong cùng một yêu cầu. Một PATCH cơ thể với ưu tiên nhưng không có record_type xóa ưu tiên. 
curl -X PATCH "https://admin.vps.org/api/v1/dns-records/4b8e2c10-7d3f-4a5b-9e6c-1a2b3c4d5e6f/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 300}'

Mã trạng thái phản hồi

200 GET, PUT hoặc PATCH: ghi chép
204 Đã xóa.
400 Lỗi xác thực
403 Đăng ký là một đăng ký hệ thống, hoặc token không có quyền cần thiết
404 Không tìm thấy, hoặc nó thuộc về tài khoản khác

Xử lý lỗi

Lỗi xác thực trả về 400 với vấn đề được khóa theo tên trường:

{
  "priority": ["MX records require a priority value"]
}

Thử nghiệm thay đổi DNS

Tìm kiếm máy phục vụ tên VPS.org trực tiếp để xác nhận thay đổi trước khi bộ nhớ đệm của bạn được tiếp nhận:

dig @ns1.vps.org example.com A
dig @ns2.vps.org example.com MX
dig @ns3.vps.org www.example.com