API di gestione DNS

Panoramica

Una zona contiene i record di un dominio. Ogni modifica che si effettua attraverso l'API viene spinta ai nameserver VPS.org immediatamente. Per servire un dominio da queste zone, impostare i nameserver al tuo registrar a ns1.vps.org, ns2.vps.org e ns3.vps.org.

Le modifiche vengono salvate e pubblicate in un solo passaggio: se i nameserver rifiutano una modifica, la richiesta restituisce 502 e nulla viene salvato. Una zona non può essere creata per un dominio che un altro account gestisce già, un genitore o un figlio di un'altra zona di account, o un nome riservato VPS.org.

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

Elenca tutte le zone DNS

Restituisce le zone, le più recenti, 25 per pagina. I record non sono inclusi qui; prendere una singola zona per ottenerli.

Parametri di query

Richiesta di esempio

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

Esempio 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

Codici di stato della risposta

Crea zona DNS

Crea una zona e la pubblica. La zona inizia con tre record NS per ns1, ns2 e ns3.vps.org, che sono record di sistema e non possono essere modificati o cancellati.

Parametri del corpo della richiesta

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

Esempio 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 stato della risposta

Ottieni i dettagli della zona DNS

Restituisce una zona con tutti i suoi record in un array di record. La risposta ha la stessa forma della risposta creata sopra.

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

Codici di stato della risposta

Elimina zona DNS

Rimuove la zona da tutti e tre i nameserver, controlla che nessuno di essi la serva ancora, e poi cancella la zona e i suoi record. Se un nameserver risponde ancora per la zona, la richiesta fallisce e la zona viene mantenuta in modo da poter riprovare.

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

Codici di stato della risposta

Elenca o Aggiungi record in una zona

GET restituisce ogni record nella zona come un array semplice (non immaginato), ordinato per tipo e nome. POST aggiunge un record alla zona e lo pubblica.

Parametri del corpo della richiesta (POST)

Richiesta di esempio

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

Esempio 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

Codici di stato della risposta

Ripubblicare una zona

Spinge nuovamente la zona e tutti i suoi record ai nameserver. Le modifiche di registrazione vengono pubblicate automaticamente, ma la pubblicazione è uno sforzo migliore e un fallimento non fallisce la richiesta originale, quindi usalo quando una modifica non compare nelle ricerche DNS. Non è necessario alcun corpo di richiesta.

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

Elenca o crea record attraverso le zone

GET restituisce i record di tutte le zone, 25 per pagina, ordinati per dominio, tipo e nome. POST crea un record come l'endpoint di zone record, ma prende la zona nel corpo come zone_uuid.

Parametri di query

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 stato della risposta

Ottieni, aggiorna o elimina un record

GET restituisce un record. PUT lo sostituisce e necessita di record_type, nome, valore e ttl. PATCH cambia solo i campi che invii. DELETE rimuove il record e restituisce 204 senza corpo. Le modifiche vengono pubblicate immediatamente. I record NS creati con la zona sono record di sistema: l'aggiornamento o l'eliminazione di essi restituisce 403.

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 stato della risposta

Gestione degli errori

Gli errori di validazione restituiscono 400 con il problema impostato dal nome del campo:

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

Verifica delle modifiche DNS

Interroga direttamente i nameserver VPS.org per confermare che una modifica è in diretta prima che la tua delega di registrar o cache risolutore raggiungano:

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