API de administración de DNS

Descripción general

Una zona contiene los registros de un dominio. Cada cambio que realice a través de la API se empuja a los servidores de nombres VPS.org de inmediato. Para servir un dominio de estas zonas, establezca sus servidores de nombres en su registrador a ns1.vps.org, ns2.vps.org y ns3.vps.org.

Los cambios se guardan y se publican en un paso: si los servidores de nombres rechazan un cambio, la solicitud devuelve 502 y nada se guarda. No se puede crear una zona para un dominio que otra cuenta ya administra, un padre o hijo de la zona de otra cuenta, o un nombre reservado de VPS.org.

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

CONSEGUIR /api/v1/dns-zones/

Listar todas las zonas DNS

Devuelve sus zonas, la más reciente primero, 25 por página. Los registros no están incluidos aquí; busque una sola zona para obtenerlas.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`domain`	string	No	Devuelve sólo la zona con exactamente este nombre de dominio
`page`	integer	No	Número de página, a partir de 1

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Campos de respuesta

Campo	Tipo	Descripción
`uuid`	string	Identificador de zona
`domain`	string	Nombre de dominio, almacenado en minúsculas
`created_at`	datetime	Tiempo de creación (ISO 8601, UTC)
`record_count`	integer	Número de registros en la zona, incluidos los tres registros del NS

Códigos de estado de respuesta

200	Éxito
403	Token API no válido o falta el token o el token carece del permiso requerido

POST /api/v1/dns-zones/

Crear zona DNS

Crea una zona y la publica. La zona comienza con tres registros NS para ns1, ns2 y ns3.vps.org, que son registros del sistema y no pueden ser editados o eliminados.

Parámetros del cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
`domain`	string	Sí	El nombre de dominio, por ejemplo.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"}'

Ejemplo de respuesta

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

Códigos de estado de respuesta

201	Zona creada
400	Nombre de dominio no válido o faltante

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

Obtener detalles de la zona DNS

Devuelve una zona con todos sus registros en un array de registros. La respuesta tiene la misma forma que la respuesta de creación arriba.

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

Códigos de estado de respuesta

200	Éxito
404	No encontrado, o pertenece a otra cuenta

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

Eliminar la zona DNS

Elimina la zona de los tres servidores de nombres, comprueba que ninguno de ellos todavía la sirve y luego borra la zona y sus registros. Si un servidor de nombres todavía responde para la zona, la petición falla y la zona se mantiene para que pueda volver a intentarlo.

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

Códigos de estado de respuesta

204	La respuesta no tiene cuerpo.
400	Un servidor de nombres todavía sirve a la zona. La zona no fue eliminada; el campo de detalles lista los errores.
404	No encontrado, o pertenece a otra cuenta

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

Listar o agregar registros en una zona

GET devuelve cada registro en la zona como un array plano (no paginado), ordenado por tipo y nombre. POST añade un registro a la zona y lo publica.

Parámetros del cuerpo de la solicitud (POST)

Parámetro	Tipo	Requerido	Descripción
`record_type`	string	Sí	A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
`name`	string	Sí	@ para el propio dominio, o una etiqueta como www. Los nombres se almacenan en minúsculas.
`value`	string	Sí	Los datos de registro, por ejemplo una dirección IP o un nombre de host. Los nombres de host no necesitan un punto de seguimiento y los valores TXT no necesitan comillas; ambos se añaden cuando el registro se publica.
`ttl`	integer	Sí	Tiempo de vivir en segundos
`priority`	integer	MX y SRV solamente	Requerido para los registros MX y SRV y ignorado para cualquier otro tipo. Para SRV, poner peso, puerto y destino en valor.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Campos de respuesta

Campo	Tipo	Descripción
`uuid`	string	Identificador del registro, utilizado por los registros /api/v1/dns/ endpoints
`priority`	integer \| null	Prioridad para los registros MX y SRV, de lo contrario nula
`created_at`	date	Fecha de creación únicamente (A-MM-DD), sin tiempo

Códigos de estado de respuesta

200	GET: los registros de la zona
201	Mensaje: registro creado
400	Error de validación, por ejemplo un tipo de registro desconocido, un ttl que falta, o un registro MX o SRV sin prioridad
404	No encontrado, o pertenece a otra cuenta

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

Reeditar una zona

Empuja la zona y todos sus registros a los servidores de nombres de nuevo. Los cambios de registro se publican automáticamente, pero la publicación es el mejor esfuerzo y un fallo no falla la solicitud original, así que utilícelo cuando un cambio no aparezca en las búsquedas DNS. No se necesita ningún cuerpo de solicitud.

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

CONSEGUIR POST /api/v1/dns-records/

Listar o crear registros en todas las zonas

GET devuelve los registros de todas sus zonas, 25 por página, ordenados por dominio, tipo y nombre. POST crea un registro como el punto final de registro de zonas, pero toma la zona en el cuerpo como zone_uuid.

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`zone`	string	No	Sólo los registros de la zona con este uuid
`record_type`	string	No	Sólo registros de este tipo, por ejemplo MX (insensible a caso)
`page`	integer	No	Número de página, a partir de 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"
    }
  ]
}

Códigos de estado de respuesta

200	GET: éxito
201	Mensaje: registro creado
400	Error de validación, o zone_uuid falta o no existe una de sus zonas

CONSEGUIR PUT PATCH BORRAR /api/v1/dns-records/{uuid}/

Obtener, actualizar o eliminar un registro

GET devuelve un registro. PUT lo reemplaza y necesita record_type, name, value y ttl. PATCH solo cambia los campos que envía. DELETE elimina el registro y devuelve 204 sin cuerpo. Los cambios se publican de inmediato. Los registros NS creados con la zona son registros del sistema: actualizarlos o eliminarlos devuelve 403.

Cuando usted PATCH la prioridad de un registro MX o SRV, envíe record_type en la misma solicitud. Un cuerpo PATCH con prioridad pero sin record_type borra la prioridad.

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

Códigos de estado de respuesta

200	GET, PUT o PATCH: el registro
204	La respuesta no tiene cuerpo.
400	Error de validación
403	El registro es un registro del sistema, o el token carece del permiso requerido
404	No encontrado, o pertenece a otra cuenta

Manejo de errores

Errores de validación devuelven 400 con el problema con el nombre de campo:

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

Pruebas de cambios en el DNS

Consultar los servidores de nombres VPS.org directamente para confirmar que un cambio está en vivo antes de que su delegación de registrador o cachés de resolución se pongan al día:

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

VPS.org API

API de administración de DNS

Descripción general

Listar todas las zonas DNS

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

Campos de respuesta

Códigos de estado de respuesta

Crear zona DNS

Parámetros del cuerpo de la solicitud

Ejemplo de respuesta

Códigos de estado de respuesta

Obtener detalles de la zona DNS

Códigos de estado de respuesta

Eliminar la zona DNS

Códigos de estado de respuesta

Listar o agregar registros en una zona

Parámetros del cuerpo de la solicitud (POST)

Ejemplo de solicitud

Ejemplo de respuesta

Campos de respuesta

Códigos de estado de respuesta

Reeditar una zona

Listar o crear registros en todas las zonas

Parámetros de consulta

Códigos de estado de respuesta

Obtener, actualizar o eliminar un registro

Códigos de estado de respuesta

Manejo de errores

Pruebas de cambios en el DNS