VPS.org API

Documentación de API REST

API de administración de DNS

Administre zonas y registros DNS mediante programación para sus dominios.

Puntos finales 4 puntos finales
Ruta base /api/v1/dns-zones
Autenticación Token del portador requerido

Descripción general

La API de DNS proporciona una gestión completa de las zonas y registros de DNS. Todas las zonas están alojadas en VPS.org servidores de nombres autorizados con generación e implementación automática de archivos de zona BIND9.

Infraestructura del servidor de nombres

Características principales

Autenticación

Todas las solicitudes de API de DNS requieren autenticación de tokens de Portador. Generar tokens de API desde el panel de control de su cuenta en /account/developers/ con los siguientes permisos:

Ejemplo

Authorization: Bearer vps_abc123def456...
Importante: Los tokens API se muestran sólo una vez durante la creación. Almacénelos de forma segura. Si pierde un token, debe generar uno nuevo.
CONSEGUIR /api/v1/dns-zones/

Listar todas las zonas DNS

Recupera una lista paginada de todas las zonas DNS propiedad del usuario autenticado. Soporta filtrado por nombre de dominio.

Parámetros de consulta

Parámetro Tipo Requerido Descripción
domain string No Filter zones by exact domain name (e.g., example.com)

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Campo Tipo Descripció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 respuesta

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

Obtener detalles de la zona DNS

Recuperar información detallada sobre una zona DNS específica, incluyendo todos los registros.

Parámetros de ruta

Parámetro Tipo Requerido Descripción
uuid string Sí Unique zone identifier

Ejemplo de respuesta

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

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

Crear zona DNS

Crear una nueva zona DNS para un dominio. La zona se implementará inmediatamente en VPS.org servidores de nombres.

Parámetros del cuerpo de la solicitud

Parámetro Tipo Requerido Descripción
domain string Sí Domain name (e.g., example.com)

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Códigos de estado de respuesta

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

Eliminar la zona DNS

Eliminar permanentemente una zona DNS y todos los registros asociados. Esta acción no se puede deshacer.

Parámetros de ruta

Parámetro Tipo Requerido Descripción
uuid string Sí Unique zone identifier

Códigos de estado de respuesta

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

Listar los registros DNS en la zona

Recuperar todos los registros DNS para una zona específica (ruta anidada).

Parámetros de ruta

Parámetro Tipo Requerido Descripción
uuid string Sí Zone UUID

Ejemplo de solicitud

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

Ejemplo de respuesta

[
  {
    "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 registro DNS en la zona

Añadir un nuevo registro DNS a una zona específica (ruta anidada).

Parámetros del cuerpo de la solicitud

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

Ejemplo de solicitud

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 respuesta

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

Administrar registros DNS (acceso directo)

Operaciones CRUD completas en registros DNS individuales usando el registro UUID.

Operaciones disponibles

Parámetros de consulta (para GET /api/v1/dns-registros/)

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

Ejemplo: Actualizar TTL de un registro

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 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 Sí
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 Sí
CAA Certificate authority authorization 0 issue "letsencrypt.org" No

Mejores prácticas

Configuración de TTL

Patrones comunes

Seguridad

Manejo de errores

Errores comunes

Código de estado Error Solución
400 Nombre de dominio no válido Asegúrese de que el dominio sigue las convenciones de nombres DNS
400 Registro MX requiere prioridad Incluir priority campo para registros MX y SRV
401 token API no válido Comprobar el formato token (debe comenzar con vps_)
403 Falta el permiso Generar nuevo token con el necesario dns:* permisos
404 Zona/registro no encontrado Verifique UUID y asegúrese de que el recurso pertenece a su cuenta

Respuesta de error de ejemplo

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

Pruebas de cambios en el DNS

Verificar la propagación de registros

# 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

Uso de herramientas en línea