VPS.org API

Documentación da API REST

API de xestión de DNS

Xestiona as zonas e os rexistros DNS mediante programación para os teus dominios.

Puntos finais 4 puntos finais
Camiño base /api/v1/dns-zones
Autenticación Requírese o token do portador

Visión xeral

A API DNS fornece unha xestión completa das zonas e rexistros DNS. Todas as zonas están hospedadas nos servidores de nomes autoritarios do VPS.org coa xeración e despliegue automáticos de ficheiros de zona BIND9.

Infraestrutura do servidor de nomes

Características principais

Autenticación

Todas as solicitudes da API DNS requiren autenticación con token de portador. Xere tokens da API desde o panel da súa conta en /account/developers/ cos seguintes permisos:

Exemplo

Authorization: Bearer vps_abc123def456...
Importante: Os tokens da API só se mostran unha vez durante a creación. Gardádeos de forma segura. Se perde un token, debe xerar un novo.
OBTER /api/v1/dns-zones/

Listar todas as zonas DNS

Obtén unha listaxe paginada de todas as zonas DNS que pertencen ao usuario autenticado. Soporta o filtrado polo nome de dominio.

Parámetros de consulta

Parámetros Tipo Obrigatorio Descrición
domain string Non Filter zones by exact domain name (e.g., example.com)

Exemplo de solicitude

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

Exemplo de resposta

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

Campos de resposta

Campo Tipo Descrición
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

Códigos de estado de resposta

200 Successfully retrieved DNS zones list
401 Unauthorized - Invalid or missing API token
403 Forbidden - Token lacks dns:list permission
OBTER /api/v1/dns-zones/{uuid}/

Obter os detalles da zona DNS

Obtén información detallada acerca dunha zona DNS específica, incluíndo todos os rexistros.

Parámetros da ruta

Parámetros Tipo Obrigatorio Descrición
uuid string Si Unique zone identifier

Exemplo de resposta

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

Códigos de estado de resposta

200 Successfully retrieved zone details
404 Zone not found or not owned by user
POST /api/v1/dns-zones/

Crear unha zona DNS

Crea unha nova zona DNS para un dominio. A zona será implementada inmediatamente en VPS.org servidores de nomes.

Parámetros do corpo da solicitude

Parámetros Tipo Obrigatorio Descrición
domain string Si Domain name (e.g., example.com)

Exemplo de solicitude

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

Exemplo de resposta

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

Códigos de estado de resposta

201 DNS zone created successfully
400 Bad Request - Invalid domain name or zone already exists
403 Forbidden - Token lacks dns:create permission
ELIMINAR /api/v1/dns-zones/{uuid}/

Eliminar a zona DNS

Elimina permanentemente unha zona DNS e todos os rexistros asociados. Esta acción non se pode desfacer.

Parámetros da ruta

Parámetros Tipo Obrigatorio Descrición
uuid string Si Unique zone identifier

Códigos de estado de resposta

204 Zone deleted successfully (no response body)
403 Forbidden - Token lacks dns:delete permission
404 Zone not found
OBTER /api/v1/dns-zones/{uuid}/records/

Lista de rexistros DNS na zona

Obter todos os rexistros DNS dunha zona específica (rota anidada).

Parámetros da ruta

Parámetros Tipo Obrigatorio Descrición
uuid string Si Zone UUID

Exemplo de solicitude

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

Exemplo de resposta

[
  {
    "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/

Crear un rexistro DNS na zona

Engadir un novo rexistro DNS a unha zona específica (rota anidada).

Parámetros do corpo da solicitude

Parámetros Tipo Obrigatorio Descrición
record_type string Si Record type: A, AAAA, CNAME, MX, TXT, NS, SRV, CAA
name string Si Record name (@ for root, subdomain, or FQDN)
value string Si 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)

Exemplo de solicitude

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

Códigos de estado de resposta

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

Xestionar os rexistros DNS (acceso directo)

Operacións CRUD completas en rexistros DNS individuais usando o UUID do rexistro.

Operacións dispoñíbeis

Parámetros da consulta (para GET / api/ v1/ dns- records /)

Parameter Tipo Descrición
zone string Filter records by zone UUID
record_type string Filter by record type (A, AAAA, MX, etc.)

Exemplo: Actualizar o TTL dun rexistro

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

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

Mellores prácticas

Configuración de TTL

Padróns comúns

Seguridade

Xestión de erros

Erros comúns

Código de estado Erro Solución
400 Nome de dominio non válido Asegurarse de que o dominio segue as convencións de nomeamento do DNS
400 O rexistro MX require prioridade Incluír priority campo para os rexistros MX e SRV
401 Token de API non válido Formato do token de comprobación (debe comezar con vps_)
403 Faltan permisos Xerar un novo token con requirido dns:* Permisos
404 Non se atopou a zona/registro Comprobar o UUID e asegurarse de que o recurso pertence á súa conta

Resposta de erro de exemplo

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

A probar os cambios de DNS

Verificar a propagación do rexistro

# 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

Usar ferramentas en liña