VPS.org API

Documentazione REST API

API di Gestione DNS

Crea zone DNS e gestisci i so record. Zone sò serviti da ns1.vps.org, ns2.vps.org e ns3.vps.org.

Punti finali 13
Percorsu di Base /api/v1/dns-zones, /api/v1/dns-records

Panoramica

Una zona cuntene i registri per un duminiu. Ogni cambiamentu chì fate attraversu l'API hè spintu immediatamente à i nomi di i servitori VPS.org. Per servì un duminiu da sti zone, impostate i so nomi di i servitori in u vostru registratore à ns1.vps.org, ns2.vps.org e ns3.vps.org.

Li canciamentu sunnu salvati e pubbricati in un passu: si li sirvizzi di nomi rifiutanu un canciu, la dumanda riturna 502 e nun si salva nudda. Una zona nun si po criari pi un duminiu chi un altru contu gestisci gia, pi na zona parinte o figliola di n'autru contu, o pi un nomu riggistratu VPS.org.

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

OTTIENI /api/v1/dns-zones/

Elencà tutte e zone DNS

Ritorna li zoni, 25 pi pagina, cchiù recenti prima. Li rigistrazzioni nun sunnu inclusi chistu, pi chistu pigghia una zona sula.

Parametri di dumanda

Parametri Tipu Obbligatoriu Descrizzioni
domain string No Ritorna sulu a zona cu esattamenti stu nomu di duminiu
page integer No U numaru di pagina, a cuminciari di 1

Esempiu di dumanda

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

Esempiu di risposta

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

Campi di risposta

Campu Tipu Descrizzioni
uuid string Identificaturi di zona
domain string Nome di duminiu, mantinutu in minusculi
created_at datetime Ora di criazzioni (ISO 8601, UTC)
record_count integer Nùmmaru di riggistrazzioni ntâ zona, ntra li quali li tri riggistrazzioni NS

Codici di Statu di Risposta

200 Successu
403 Token API mancante o nun validu, o u token nun havi li permessi richiesti
POST /api/v1/dns-zones/

Crea una zona DNS

Cria na zona e la pubblica. La zona accumincia cu tri rigistrazzioni NS pi ns1, ns2 e ns3.vps.org, ca sunnu rigistrazzioni di sistema e nun ponnu èssiri canciati o canciati.

Parametri di u Corpu di a Richiesta

Parametri Tipu Obbligatoriu Descrizzioni
domain string Iè U nomu di duminiu, pi esempiu 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"}'

Esempiu di risposta

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

Codici di Statu di Risposta

201 Zona criata
400 U nomu di duminiu manca o ùn hè micca validu
OTTIENI /api/v1/dns-zones/{uuid}/

Get DNS Zone Details

Ritorna una zona cu tutti i so record in un array di record. A risposta hà a stissa forma di la risposta di creazione supra.

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

Codici di Statu di Risposta

200 Successu
404 Non truvatu, o appartiene a un altru contu
SCANCÀ /api/v1/dns-zones/{uuid}/

Eliminà a zona DNS

Rimuvi la zona di tutti e tri li sirvizzi di nomi, verifica ca nuddu di iḍḍi la servi ancora, e poi cancia la zona e li so rigistrazzioni. Si un sirvizziu di nomi rispunni ancora â zona, la dumanda fallisci e la zona si mantini pi putiri ripruvari.

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

Codici di Statu di Risposta

204 Canciatu. A risposta nun havi corpu.
400 Un sirvizziu di nomi servi ancora a zona. A zona nun fu canciata; u campu di dittagghi elenca l'erruri.
404 Non truvatu, o appartiene a un altru contu
OTTIENI POST /api/v1/dns-zones/{uuid}/records/

Lista o Aggiungi Record in una Zona

GET riturna ogni record ntâ zona comu na matrici (non paginizzata), ordinata pi tipu e nomu. POST agghiunci un record â zona e lu pubbrica.

Parametri di u Corpu di a Richiesta (POST)

Parametri Tipu Obbligatoriu Descrizzioni
record_type string Iè A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
name string Iè @ pi lu duminiu stissu, o n' etichetta comu www. I nomi sunnu sarbati in minusculi.
value string Iè Li dati di u record, pi esempiu un indirizzu IP o un nomu di òspite. Li nomi di òspiti nun hannu bisognu di un puntu finali e li valuri TXT nun hannu bisognu di virgolette; tutti dui sunnu agghiunti quannu u record è pubblicatu.
ttl integer Iè Tempu di vita in sicondi
priority integer Solu MX e SRV Richiesta pi li record MX e SRV e ignorata pi tutti l'autri tipi. Pi SRV, mettiti u pesu, u portu e u scopu ntô valuri.

Esempiu di dumanda

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

Esempiu di risposta

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

Campi di risposta

Campu Tipu Descrizzioni
uuid string L'identificativu dû record, usatu dî punti finali di /api/v1/dns-records/
priority integer | null Priorità pi li rigistrazzioni MX e SRV, altrimenti null
created_at date Sulu a data di criazzioni (A-MM-DD), senza ora

Codici di Statu di Risposta

200 GET: i rigistrazzioni di a zona
201 POST: record creatu
400 Errori di validità, pi esempiu un tipu di record sconosciutu, un ttl mancante, o un record MX o SRV senza priorità
404 Non truvatu, o appartiene a un altru contu
POST /api/v1/dns-zones/{uuid}/sync/

Ripubbricari na zona

Rispinci la zona e tutti li so rigistrazzioni a li sirvizzi di nomi. Li canci di rigistrazzioni sunnu pubblicati automaticamenti, ma la pubblicazzioni è lu megghiu sforzu e un fallimentu nun fa falliri la richiesta originali, adunca usalu quannu un canciu nun appare ntâ ricerca DNS. Nudda richiesta di corpu è necessaria.

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

Ricerca

GET ritorna i record di tutte e zone, 25 per pagina, ordinati per duminiu, tipu e nome. POST crea un record cum'è u puntu finale di i registri di zona, ma piglia a zona in u corpu cum'è zone_uuid.

Parametri di dumanda

Parametri Tipu Obbligatoriu Descrizzioni
zone string No sulu li rigistrazzioni dâ zona cu stu uuid
record_type string No Sulu i record di stu tipu, pi esempiu MX (senza distinzioni ntra maiusculi e minusculi)
page integer No U numaru di pagina, a cuminciari di 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"
    }
  ]
}

Codici di Statu di Risposta

200 Successu
201 POST: record creatu
400 Errori di validazzioni, o zone_uuid manca o ùn hè micca una di li zoni
OTTIENI PUT PATCH SCANCÀ /api/v1/dns-records/{uuid}/

Riciviri, aggiorna o cancella un record

GET riturna un record. PUT lu rimpiazza e ci vole record_type, name, value e ttl. PATCH cancia sulu li campi ca mandate. DELETE liscia u record e riturna 204 senza corpu. I canciamentu sunnu pubblicati immediatamenti. I record NS criati cu la zona sunnu record di sistema: l'aggiornamentu o a cancellazione li riturna 403.

Quannu si PATCH la priurità di un record MX o SRV, manda record_type ntâ stissa richiesta. Un corpu PATCH cu priurità ma senza record_type netti la priurità. 
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}'

Codici di Statu di Risposta

200 GET, PUT o PATCH: u record
204 Canciatu. A risposta nun havi corpu.
400 Validazione
403 U record è un record di sistema, o u token nun àvi li permessi richiesti
404 Non truvatu, o appartiene a un altru contu

Gestione di l'errori

Errori di validità riturnà 400 cu lu problema chiudata da u nomu di u campu:

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

Testing DNS Changes

Interroga i nomi VPS.org direttamente per cunfirmà un cambiamentu prima di a vostra delegazione di registratore o cache di risolvente:

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