VPS.org API

Documentare API REST

API-ul de gestionare DNS

Creează zone DNS și gestionează înregistrările lor. Zonele sunt servite de ns1.vps.org, ns2.vps.org și ns3.vps.org.

Puncte finale 13
Calea de bază /api/v1/dns-zones, /api/v1/dns-records

Prezentare generală

O zonă deține înregistrările pentru un domeniu. Fiecare schimbare pe care o faceți prin API este împinsă la serverele de nume VPS.org imediat. Pentru a servi un domeniu din aceste zone, setați-și serverele de nume la registrar la ns1.vps.org, ns2.vps.org și ns3.vps.org.

Modificări sunt salvate și publicate într-un pas: dacă serverele refuză o modificare, cererea returnează 502 și nimic nu este salvat. O zonă nu poate fi creată pentru un alt cont de domeniu deja gestionează, un părinte sau un copil al altui cont, sau un nume rezervat VPS.org.

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

OBŢINE /api/v1/dns-zones/

Listați toate zonele DNS

Returnează zonele dumneavoastră, cele mai noi, 25 pe pagină. Înregistrările nu sunt incluse aici; adu o singură zonă pentru a le obține.

Parametrii de interogare

Parametrul Tip Necesar Descriere
domain string Nu. Returnează doar zona cu exact acest nume de domeniu
page integer Nu. Numărul de pagină, începând cu 1

Exemplu de solicitare

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

Exemplu de răspuns

{
  "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âmpuri de răspuns

Câmp Tip Descriere
uuid string Identificator de zona
domain string Nume domeniu, stocat în minuscule
created_at datetime Ora de creare (ISO 8601, UTC)
record_count integer Numărul de înregistrări în zona, inclusiv cele trei înregistrări NS

Coduri de stare a răspunsului

200 Succes
403 Token API lipsă sau nu este valid, sau tokenul nu este permisul necesar
POST /api/v1/dns-zones/

Creează zona DNS

Creează o zonă și îl publică. Zona începe cu trei înregistrări NS pentru ns1, ns2 și ns3.vps.org, care sunt înregistrări de sistem și nu pot fi editate sau șterse.

Parametrii corpului cererii

Parametrul Tip Necesar Descriere
domain string Da Numele domeniu, de exemplu.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"}'

Exemplu de răspuns

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

Coduri de stare a răspunsului

201 Zona creată
400 Nume de domeniu lipsă sau nu
OBŢINE /api/v1/dns-zones/{uuid}/

Obține detalii ale zonei DNS

Returnează o zonă cu toate înregistrările sale într-un array de înregistrări. Răspunsul are aceeași formă ca răspunsul creat de mai sus.

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

Coduri de stare a răspunsului

200 Succes
404 Nu a fost găsit, sau aparţine unui alt cont
ŞTERGE /api/v1/dns-zones/{uuid}/

Șterge zona DNS

Îndepărtează zona din toate cele trei servere de nume, verifică că niciunul dintre ei nu îl mai servește, și apoi șterge zona și înregistrările sale. Dacă un server de nume încă răspunde pentru zona, cererea eșuează și zona este păstrată astfel încât să poți încerca.

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

Coduri de stare a răspunsului

204 A fost eliminat.
400 Un server de nume încă servește zona. Zona nu a fost șterse; câmpul de detaliu enumera erorile.
404 Nu a fost găsit, sau aparţine unui alt cont
OBŢINE POST /api/v1/dns-zones/{uuid}/records/

Listă sau adaugă înregistrări într-o zonă

GET returnează fiecare record din zonă ca un array simplu (nu paginat), sortat după tip și nume. POST adaugă un record în zona și îl publică.

Parametrii corpului cererii (POST)

Parametrul Tip Necesar Descriere
record_type string Da A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
name string Da @ pentru domeniul în sine, sau o etichetă cum ar fi www. Nume sunt stocate în minuscule.
value string Da Datele de înregistrare, de exemplu o adresă IP sau un host. Nu sunt necesare un punct de urgență și valorile TXT nu au nevoie de citații; ambele sunt adăugate atunci când înregistrarea este publicată.
ttl integer Da Timp de a trăi în secunde
priority integer Numai MX și SRV Requis pentru înregistrările MX și SRV și ignorat pentru orice alt tip. Pentru SRV, pune greutate, port și țintă în valoare.

Exemplu de solicitare

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

Exemplu de răspuns

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

Câmpuri de răspuns

Câmp Tip Descriere
uuid string Identificator de înregistrare, utilizat de înregistrările/endpointele /api/v1/dns
priority integer | null Prioritate pentru înregistrările MX și SRV, altfel nul
created_at date Data de creare numai (A-MM-DD), fără o perioadă

Coduri de stare a răspunsului

200 GET: înregistrările zonei
201 POST: înregistrarea creată
400 Eroare de validare, de exemplu un tip de record necunoscut, un TTL lipsă, sau un record MX sau SRV fără prioritate
404 Nu a fost găsit, sau aparţine unui alt cont
POST /api/v1/dns-zones/{uuid}/sync/

Republică o zonă

Împinge zona și toate înregistrările sale la serverele de nume din nou. Schimbările de înregistrare sunt publicate automat, dar efortul eliberează publicarea este cel mai bun și un eșec nu eșuează cererea originală, astfel încât să utilizați acest lucru atunci când o modificare nu apare în căutarea DNS. Nu este nevoie de corp de cerere.

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

Lista sau crearea de înregistrări în zone

GET returnează înregistrările tuturor zonelor dumneavoastră, 25 pe pagină, comandate după domeniu, tip și nume. POST creează un înregistrare ca înregistrarea zonei, dar ia zona în corp ca zone_uuid.

Parametrii de interogare

Parametrul Tip Necesar Descriere
zone string Nu. Numai înregistrările zonei cu acest uuid
record_type string Nu. Numai înregistrările de acest tip, de exemplu MX (insensibil la caz)
page integer Nu. Numărul de pagină, începând cu 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"
    }
  ]
}

Coduri de stare a răspunsului

200 GET: succes
201 POST: înregistrarea creată
400 Eroare de validare, sau zona_uuid lipsește sau nu este una dintre zonele dumneavoastră
OBŢINE PUT PATCH ŞTERGE /api/v1/dns-records/{uuid}/

Obține, actualizează sau șterge un înregistrare

GET returnează un record. PUT îl înlocuiește și are nevoie de record_type, nume, valoare și TTL. PATCH schimbă doar câmpurile trimise. DELETE șterge recordul și returnează 204 fără corp. Modificări sunt publicate imediat. Înregistrările NS create cu zona sunt înregistrările sistemului: actualizarea sau eliminarea lor returnează 403.

Când veți PACTH prioritatea unui record MX sau SRV, trimiteți record_type în aceeași cerere. Un corp PATCH cu prioritate, dar fără record_type clarifică prioritatea. 
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}'

Coduri de stare a răspunsului

200 GET, PUT sau PATCH: recordul
204 A fost eliminat.
400 Eroare de validare
403 Înregistrarea este un sistem de înregistrare, sau tokenul lipsește permisiunea necesară
404 Nu a fost găsit, sau aparţine unui alt cont

Eroare de manipulare

Eroare de validare returnează 400 cu problema cheiată prin nume de câmp:

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

Testarea modificărilor DNS

Interoghează serverele de nume VPS.org direct pentru a confirma o modificare este live înainte de delegarea registrar sau cache-urile de soluționare prinderea:

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