API di Gestione DNS

Panoramica

L'API DNS fornisce una gestione completa di e zone è i record DNS. Tutte e zone sò ospitate in i nameservers autoritari di VPS.org cù a generazione è u dispiegamentu di i file di zona BIND9 automatici.

Servituri di nomi

ns1.vps.org (38.248.6.195) - Master primariu cu firma in linea DNSSEC
ns2.vps.org (38.248.6.196) - Sclava sicunnària
ns3.vps.org (38.248.6.197) - Sclava sicunnària

Caratteristichi chiavi

Generazioni è dispiegamentu di file di zona BIND9
Trasferimenti di zona via l'autenticazione TSIG (replicazione master-slave)
Supportu per tutti i principali tipi di record DNS (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
Filtraggio di nomi di duminiu e identificazione di zona basata su UUID
Routes niditati pi la gestione di li rigistrazzioni specifici di zona

Autentificazione

Tutte e dumande API DNS richiedenu l'autenticazione di u token di u portatore. Generate token API da u vostru dashboard di u contu à /account/developers/ cun li seguenti permessi:

dns:list - Vedi i zoni è i registri DNS
dns:create - Crea novi zoni e rigistrazioni
dns:update - Modificari li zoni e li rigistrazzioni esistenti
dns:delete - Eliminari zoni e rigistrazzioni
dns:* - Accessu cumpletu à a gestione DNS

Esempiu

Authorization: Bearer vps_abc123def456...

Importanti: Li token API sunnu mustrati sulu una vota duranti la criazzioni. Mantinilli sicuri. Si perdite un token, avete a ginirànnunu unu novu.

OTTIENI /api/v1/dns-zones/

Elencà tutte e zone DNS

Ricugghiri na lista pagintata di tutti li zoni DNS di prupietà di l'utilizaturi autenticatu. Supporta u filtraggiu pi nomu di duminiu.

Parametri di dumanda

Parametri	Tipu	Obbligatoriu	Descrizzioni
`domain`	string	No	Filter zones by exact domain name (e.g., `example.com`)

Esempiu di dumanda

cURL

Python

JavaScript

curl -X GET "https://admin.vps.org/api/v1/dns-zones/" \
  -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)
print(response.json())

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  headers: {'Authorization': 'Bearer YOUR_API_TOKEN'}
});

const zones = await response.json();
console.log(zones);

Esempiu di risposta

[
  {
    "uuid": "abc123-def456-ghi789",
    "domain": "example.com",
    "created_at": "2024-01-15T10:30:00Z",
    "record_count": 12
  },
  {
    "uuid": "xyz789-uvw456-rst123",
    "domain": "myapp.io",
    "created_at": "2024-06-20T14:15:00Z",
    "record_count": 8
  }
]

Campi di risposta

Campu	Tipu	Descrizzioni
`uuid`	string	Unique zone identifier (used in API requests)
`domain`	string	Domain name for this DNS zone
`created_at`	datetime	Zone creation timestamp (ISO 8601 format)
`record_count`	integer	Total number of DNS records in this zone

Codici di Statu di Risposta

200	Successfully retrieved DNS zones list
401	Unauthorized - Invalid or missing API token
403	Forbidden - Token lacks `dns:list` permission

OTTIENI /api/v1/dns-zones/{uuid}/

Get DNS Zone Details

Ricugghiri nfurmazzioni dittagghiati ncapu a na zona DNS spicifica, cumpresi tutti i record.

Parametri di u percorsu

Parametri	Tipu	Obbligatoriu	Descrizzioni
`uuid`	string	Iè	Unique zone identifier

Esempiu di risposta

{
  "uuid": "abc123-def456-ghi789",
  "domain": "example.com",
  "created_at": "2024-01-15T10:30:00Z",
  "record_count": 5,
  "records": [
    {
      "uuid": "rec-001",
      "record_type": "A",
      "name": "@",
      "value": "192.0.2.1",
      "ttl": 3600,
      "priority": null,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "uuid": "rec-002",
      "record_type": "MX",
      "name": "@",
      "value": "mail.example.com",
      "ttl": 3600,
      "priority": 10,
      "created_at": "2024-01-15T10:32:00Z"
    }
  ]
}

Codici di Statu di Risposta

200	Successfully retrieved zone details
404	Zone not found or not owned by user

POST /api/v1/dns-zones/

Crea una zona DNS

Crea na nova zona DNS pi nu duminiu. La zona si dispiegherà immediatamenti a VPS.org sirvitori di nomi.

Parametri di u Corpu di a Richiesta

Parametri	Tipu	Obbligatoriu	Descrizzioni
`domain`	string	Iè	Domain name (e.g., `example.com`)

Esempiu di dumanda

cURL

Python

JavaScript

curl -X POST "https://admin.vps.org/api/v1/dns-zones/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "newdomain.com"}'

import requests

url = "https://admin.vps.org/api/v1/dns-zones/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {"domain": "newdomain.com"}

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

const response = await fetch('https://admin.vps.org/api/v1/dns-zones/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({domain: 'newdomain.com'})
});

const zone = await response.json();
console.log(zone);

Esempiu di risposta

{
  "uuid": "new-zone-uuid",
  "domain": "newdomain.com",
  "created_at": "2026-01-18T16:45:00Z",
  "record_count": 0,
  "records": []
}

Codici di Statu di Risposta

201	DNS zone created successfully
400	Bad Request - Invalid domain name or zone already exists
403	Forbidden - Token lacks `dns:create` permission

SCANCÀ /api/v1/dns-zones/{uuid}/

Eliminà a zona DNS

Elimina definitivamenti na zona DNS e tutti li so rigistrazzioni. Sta azzioni nun pò èssiri annullata.

Parametri di u percorsu

Parametri	Tipu	Obbligatoriu	Descrizzioni
`uuid`	string	Iè	Unique zone identifier

Codici di Statu di Risposta

204	Zone deleted successfully (no response body)
403	Forbidden - Token lacks `dns:delete` permission
404	Zone not found

OTTIENI /api/v1/dns-zones/{uuid}/records/

Lista di i registri DNS in zona

Ricuperà tutti i record DNS per una zona specifica (route nidificata).

Parametri di u percorsu

Parametri	Tipu	Obbligatoriu	Descrizzioni
`uuid`	string	Iè	Zone UUID

Esempiu di dumanda

curl -X GET "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Esempiu di risposta

[
  {
    "uuid": "rec-001",
    "record_type": "A",
    "name": "@",
    "value": "192.0.2.1",
    "ttl": 3600,
    "priority": null,
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "uuid": "rec-002",
    "record_type": "MX",
    "name": "@",
    "value": "mail.example.com",
    "ttl": 3600,
    "priority": 10,
    "created_at": "2024-01-15T10:32:00Z"
  }
]

POST /api/v1/dns-zones/{uuid}/records/

Crea un record DNS in Zona

Aggiungi un novu record DNS à una zona spicifica (route annidata).

Parametri di u Corpu di a Richiesta

Parametri	Tipu	Obbligatoriu	Descrizzioni
`record_type`	string	Iè	Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
`name`	string	Iè	Record name (`@` for root, subdomain, or FQDN)
`value`	string	Iè	Record value (IP address, hostname, text)
`ttl`	integer	No	Time to live in seconds (default: 3600)
`priority`	integer	For MX/SRV	Priority (required for MX and SRV records)

Esempiu di dumanda

cURL

Python

curl -X POST "https://admin.vps.org/api/v1/dns-zones/{uuid}/records/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
  }'

import requests

url = f"https://admin.vps.org/api/v1/dns-zones/{zone_uuid}/records/"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "record_type": "A",
    "name": "www",
    "value": "192.0.2.1",
    "ttl": 3600
}

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

Codici di Statu di Risposta

201	DNS record created successfully
400	Bad Request - Invalid parameters or validation error (e.g., MX record missing priority)

GET PUT PATCH DELETE /api/v1/dns-records/{uuid}/

Gestisce i registri DNS (accessu direttu)

Operazioni CRUD cumpleti supra i singuli registri DNS usannu u record UUID.

Operazioni dispunibbili

GET /api/v1/dns-records/{uuid}/ - Retrieve record details
PUT /api/v1/dns-records/{uuid}/ - Full update (all fields required)
PATCH /api/v1/dns-records/{uuid}/ - Partial update (only changed fields)
DELETE /api/v1/dns-records/{uuid}/ - Delete record

Parametri di query (per GET /api/v1/dns-records/)

Parameter	Tipu	Descrizzioni
`zone`	string	Filter records by zone UUID
`record_type`	string	Filter by record type (A, AAAA, MX, etc.)

Esempiu: Aggiornamentu TTL di un record

curl -X PATCH "https://admin.vps.org/api/v1/dns-records/{rec-uuid}/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": 1800}'

Supported DNS Record Types

Tipu	Purpose	Example Value	Priority Required
A	Maps domain to IPv4 address	192.0.2.1	No
AAAA	Maps domain to IPv6 address	2001:0db8::1	No
CNAME	Creates alias to another domain	example.com	No
MX	Mail server for domain	mail.example.com	Iè
TXT	Text record (SPF, DKIM, verification)	v=spf1 include:_spf.google.com ~all	No
NS	Nameserver delegation	ns1.example.com	No
SRV	Service location record	10 5060 sip.example.com	Iè
CAA	Certificate authority authorization	0 issue "letsencrypt.org"	No

Migliori pratiche

Configurazione TTL

Produzione (stabile): 3600-86400 siconni (1-24 ore)
Prima di a migrazioni: 300-600 secondi (5-10 minuti) - TTL più bassu prima di i cambiamenti pianificati
Sviluppu: 300-1800 secondi (5-30 minuti) per test più veloci

Pattern

Dominiu radici (@): Usari i registri A/AAAA, no CNAME
www suttadomeniu: Puderà usari u puntamentu CNAME a radici o à un record A separatu
Email (MX): Includiri sempri a prifirenza, nùmmaru cchiù vasciu = prifirenza cchiù àuta
CNAME: Non pò coesistiri cu àutri tipi di record cu lu stissu nomu

Sicurità

CAA Records: Spiegificà quali CA pò emèttiri certificati
SPF/DKIM/DMARC: Configura l'autenticazione di l'e-mail pi impediri l'usu di identità falsi
Audits regulari: Rivisioni di i registri DNS trimestrali, rimuvi e voci inutili

Gestione di l'errori

Errori cumuni

Codice di Statu	Errori	Soluzioni
400	Nome di duminiu	Assicurassi ca u duminiu seguita i cunvenzioni di nomi DNS
400	U record MX hà bisognu di prifirenza	Includi `priority` campu pi li record MX e SRV
401	Token API nun validu	Verifica u furmatu di u token (devi accuminciari cu `vps_`)
403	Mancanu li permessi	Genera un novu token cu richiesti `dns:*` Permessi
404	Zona/record nun truvatu	Verifica l'UUID e assicurati ca la risursa apparti a lu to contu

Risposta di errore d'esempiu

{
  "detail": "MX records require a priority value",
  "error_code": "validation_error",
  "field": "priority"
}

Testing DNS Changes

Verifica la prupagazione di li rigistrazzioni

# Query A record
dig example.com A

# Query specific nameserver
dig @ns1.vps.org example.com

# Query MX records
dig example.com MX

# Check all records
dig example.com ANY

Utilizà strumenti in linea

whatsmydns.net: Check global DNS propagation
dnschecker.org: Multi-location DNS lookup
mxtoolbox.com: Email-related DNS testing

VPS.org API

API di Gestione DNS

Panoramica

Servituri di nomi

Caratteristichi chiavi

Autentificazione

Esempiu

Elencà tutte e zone DNS

Parametri di dumanda

Esempiu di dumanda

Esempiu di risposta

Campi di risposta

Codici di Statu di Risposta

Get DNS Zone Details

Parametri di u percorsu

Esempiu di risposta

Codici di Statu di Risposta

Crea una zona DNS

Parametri di u Corpu di a Richiesta

Esempiu di dumanda

Esempiu di risposta

Codici di Statu di Risposta

Eliminà a zona DNS

Parametri di u percorsu

Codici di Statu di Risposta

Lista di i registri DNS in zona

Parametri di u percorsu

Esempiu di dumanda

Esempiu di risposta

Crea un record DNS in Zona

Parametri di u Corpu di a Richiesta

Esempiu di dumanda

Codici di Statu di Risposta

Gestisce i registri DNS (accessu direttu)

Operazioni dispunibbili

Parametri di query (per GET /api/v1/dns-records/)

Esempiu: Aggiornamentu TTL di un record

Supported DNS Record Types

Migliori pratiche

Configurazione TTL

Pattern

Sicurità

Gestione di l'errori

Errori cumuni

Risposta di errore d'esempiu

Testing DNS Changes

Verifica la prupagazione di li rigistrazzioni

Utilizà strumenti in linea