VPS.org API

Dokumentasi API REST

API Pengurusan DNS

Cipta zon DNS dan urus rekod mereka. Zon dilayan oleh ns1.vps.org, ns2.vps.org dan ns3.vps.org.

Titik akhir 13
Laluan Asas /api/v1/dns-zones, /api/v1/dns-records

Gambaran Keseluruhan

Zon menyimpan rekod untuk satu domain. Setiap perubahan yang anda buat melalui API ditolak ke pelayan nama VPS.org dengan serta merta. Untuk berkhidmat domain dari zon ini, tetapkan pelayan nama di pengurus anda kepada ns1.vps.org, ns2.vps.org dan ns3.vps.org.

Perubahan disimpan dan diterbitkan dalam satu langkah: jika pelayan nama menolak perubahan, permintaan mengembalikan 502 dan tiada apa disimpan. Zon tidak boleh dicipta untuk domain yang akaun lain sudah urus, ibu bapa atau anak zon akaun lain, atau nama terpelihara VPS.org.

Keizinan diperlukan: dns:list (GET), dns:create (POST), dns:update (PUT, PATCH, sync), dns:delete (DELETE), dns:*

DAPATKAN /api/v1/dns-zones/

Senaraikan Semua Zon DNS

Kembalikan zon anda, terkini pertama, 25 per halaman. Rekod tidak termasuk di sini; ambil zon tunggal untuk mendapatkannya.

Parameter Pertanyaan

Parameter Jenis Diperlukan Huraian
domain string Tidak Kembalikan hanya zon dengan nama domain ini
page integer Tidak Nombor halaman, bermula pada 1

Contoh Permintaan

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

Contoh Respons

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

Medan Respons

Medan Jenis Huraian
uuid string Pengecam Zon
domain string Nama domain, disimpan dalam huruf kecil
created_at datetime Masa penciptaan (ISO 8601, UTC)
record_count integer Bilangan rekod dalam zon, termasuk tiga rekod NS

Kod Status Respons

200 Kejayaan
403 Token API hilang atau tidak sah, atau token tidak mempunyai keizinan yang diperlukan
POST /api/v1/dns-zones/

Cipta Zon DNS

Cipta zon dan menerbitkannya. Zon bermula dengan tiga rekod NS untuk ns1, ns2 dan ns3.vps.org, yang rekod sistem dan tidak boleh disunting atau dipadam.

Minta Parameter Badan

Parameter Jenis Diperlukan Huraian
domain string Ya Nama domain, contohnya 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"}'

Contoh Respons

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

Kod Status Respons

201 Zon dicipta
400 Nama domain hilang atau tidak sah
DAPATKAN /api/v1/dns-zones/{uuid}/

Dapatkan Perincian Zon DNS

Kembalikan satu zon dengan semua rekodnya dalam aras rekod. Balasan mempunyai bentuk yang sama seperti balasan cipta di atas.

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

Kod Status Respons

200 Kejayaan
404 Tidak dijumpai, atau ia milik akaun lain
PADAM /api/v1/dns-zones/{uuid}/

Hapuskan Zon DNS

Buang zon dari semua tiga pelayan nama, semak bahawa tiada satu pun daripadanya masih berkhidmat kepadanya, dan kemudian padam zon dan rekodnya. Jika pelayan nama masih menjawab untuk zon, permintaan gagal dan zon disimpan supaya anda boleh cuba lagi.

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

Kod Status Respons

204 Dipadam. Balasan tidak mempunyai badan.
400 Pelayan nama masih melayan zon. Zon tidak dipadam; medan perincian menyenaraikan ralat.
404 Tidak dijumpai, atau ia milik akaun lain
DAPATKAN POST /api/v1/dns-zones/{uuid}/records/

Senarai atau Tambah Rekod dalam Zon

GET mengembalikan setiap rekod dalam zon sebagai aras biasa (tidak dipagekan), diisih mengikut jenis dan nama. POST menambah rekod ke zon dan menerbitkannya.

Minta Parameter Badan (POST)

Parameter Jenis Diperlukan Huraian
record_type string Ya A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
name string Ya @ untuk domain sendiri, atau label seperti www. Nama disimpan dalam huruf kecil.
value string Ya Data rekod, contohnya alamat IP atau nama hos. Nama hos tidak memerlukan titik akhir dan nilai TXT tidak memerlukan petikan; kedua-duanya ditambah apabila rekod diterbitkan.
ttl integer Ya Masa untuk hidup dalam saat
priority integer Hanya MX dan SRV Diperlukan untuk rekod MX dan SRV dan diabaikan untuk semua jenis lain. Untuk SRV, masukkan berat, port dan sasaran dalam nilai.

Contoh Permintaan

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

Contoh Respons

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

Medan Respons

Medan Jenis Huraian
uuid string Pengenalpasti rekod, digunakan oleh /api/v1/dns-records/ titik akhir
priority integer | null Keutamaan untuk rekod MX dan SRV, jika tidak kosong
created_at date Tarikh penciptaan sahaja (Y-MM-DD), tanpa masa

Kod Status Respons

200 GET: rekod zon
201 POST: rekod dicipta
400 Ralat pengesahan, contohnya jenis rekod tidak diketahui, ttl hilang, atau rekod MX atau SRV tanpa keutamaan
404 Tidak dijumpai, atau ia milik akaun lain
POST /api/v1/dns-zones/{uuid}/sync/

Terbitkan semula Zon

Tolak zon dan semua rekodnya ke pelayan nama lagi. Perubahan rekod diterbitkan secara automatik, tetapi penerbitan adalah usaha terbaik dan kegagalan tidak gagalkan permintaan asal, jadi gunakan ini apabila perubahan tidak muncul dalam pencarian DNS. Tiada badan permintaan diperlukan.

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"
}
DAPATKAN POST /api/v1/dns-records/

Senarai atau Cipta Rekod Melalui Zon

GET mengembalikan rekod semua zon anda, 25 per halaman, diiringi oleh domain, jenis dan nama. POST mencipta rekod seperti titik akhir rekod zon, tetapi mengambil zon dalam badan sebagai zone_uuid.

Parameter Pertanyaan

Parameter Jenis Diperlukan Huraian
zone string Tidak Hanya rekod zon dengan uuid ini
record_type string Tidak Hanya rekod jenis ini, contohnya MX (kas tidak sensitif)
page integer Tidak Nombor halaman, bermula pada 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"
    }
  ]
}

Kod Status Respons

200 GET: kejayaan
201 POST: rekod dicipta
400 Ralat pengesahan, atau zone_uuid hilang atau bukan salah satu zon anda
DAPATKAN PUT PATCH PADAM /api/v1/dns-records/{uuid}/

Dapatkan, kemaskini atau padam rekod

GET mengembalikan satu rekod. PUT menggantikan dan memerlukan record_type, nama, nilai dan ttl. PATCH hanya mengubah medan yang anda hantar. DELETE menghapuskan rekod dan mengembalikan 204 tanpa badan. Perubahan diterbitkan dengan segera. Rekod NS yang dicipta dengan zon adalah rekod sistem: mengemaskini atau memadamnya mengembalikan 403.

Apabila anda PATCH keutamaan rekod MX atau SRV, hantar record_type dalam permintaan yang sama. Badan PATCH dengan keutamaan tetapi tanpa record_type akan kosongkan keutamaan. 
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}'

Kod Status Respons

200 GET, PUT atau PATCH: rekod
204 Dipadam. Balasan tidak mempunyai badan.
400 Ralat pengesahan
403 Rekod adalah rekod sistem, atau token tidak mempunyai keizinan yang diperlukan
404 Tidak dijumpai, atau ia milik akaun lain

Pengendalian Ralat

Ralat pengesahan mengembalikan 400 dengan masalah ditandakan oleh nama medan:

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

Uji Perubahan DNS

Tanya pelayan nama VPS.org secara langsung untuk mengesahkan perubahan adalah hidup sebelum delegasi pengurus atau cache penyelesai anda mengejar:

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