API de gerenciamento de DNS

Visão geral

Uma zona mantém os registros para um domínio. Cada mudança que você faz através da API é empurrada para os servidores de nomes VPS.org imediatamente. Para servir um domínio a partir dessas zonas, coloque seus servidores de nomes em seu registrador para ns1.vps.org, ns2.vps.org e ns3.vps.org.

As alterações são salvas e publicadas em um passo: se os servidores de nomes recusam uma alteração, o pedido devolve 502 e nada é salvo. Uma zona não pode ser criada para um domínio outra conta já gerencia, um pai ou filho de outra zona de conta, ou um nome reservado VPS.org.

Permissão requerida: dns:list (GET), dns:create (POST), dns:update (PUT, PATCH, sync), dns:delete (DELETE), dns:*

PEGAR /api/v1/dns-zones/

Listar todas as zonas DNS

Devolve suas zonas, mais recentes, 25 por página. Os registros não estão incluídos aqui; pegue uma única zona para obtê-las.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`domain`	string	Não	Devolver apenas a zona com exatamente este nome de domínio
`page`	integer	Não	Número de página, a partir de 1

Exemplo de solicitação

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

Exemplo de resposta

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

Campo	Tipo	Descrição
`uuid`	string	Identificador de zona
`domain`	string	Nome de domínio, armazenado em minúsculas
`created_at`	datetime	Hora de criação (ISO 8601, UTC)
`record_count`	integer	Número de registos na zona, incluindo os três registros NS

Códigos de status de resposta

200	Sucesso
403	Token API faltante ou inválida, ou o token carece da permissão requerida

POST /api/v1/dns-zones/

Criar uma Zona DNS

Cria uma zona e publica. A zona começa com três registros NS para ns1, ns2 e ns3.vps.org, que são registros de sistema e não podem ser editados ou excluídos.

Parâmetros do corpo da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`domain`	string	Sim	O nome de domínio, por exemplo, exemplo.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"}'

Exemplo de resposta

{
  "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 status de resposta

201	Zona criada
400	Nome de domínio inválido ou faltante

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

Obter detalhes da zona DNS

Devolve uma zona com todos os seus registros em um array de registros. A resposta tem a mesma forma que a resposta criada acima.

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 status de resposta

200	Sucesso
404	Não encontrado, ou pertence a outra conta

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

Apagar a Zona DNS

Remove a zona dos três servidores de nomes, verifica que nenhum deles ainda o serventão apaga a zona e seus registros. Se um servidor de nomes ainda responder para a zona, o pedido falha e a zona é mantida para que você possa tentar novamente.

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 status de resposta

204	A resposta não tem corpo.
400	Um servidor de nomes ainda serve a zona. A zona não foi excluída; o campo de detalhes lista os erros.
404	Não encontrado, ou pertence a outra conta

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

Listar ou adicionar registos numa zona

O EGT devolve cada registro na zona como um array simples (não paginado), ordenado por tipo e nome. O POST adiciona um registro à zona e publica-o.

Parâmetros do corpo da requisição (POST)

Parâmetro	Tipo	Obrigatório	Descrição
`record_type`	string	Sim	A, AAAA, CNAME, MX, NS, TXT, SRV, PTR, SOA, CAA
`name`	string	Sim	@ para o próprio domínio, ou uma etiqueta como www. Os nomes são armazenados em minúsculas.
`value`	string	Sim	Os dados de registro, por exemplo um endereço IP ou um hostname. Os nomes de máquina não precisam de um ponto de rastreamento e os valores TXT não precisam de citações; ambos são adicionados quando o registro é publicado.
`ttl`	integer	Sim	Tempo para viver em segundos
`priority`	integer	Apenas MX e SRV	Requerido para registros MX e SRV e ignorado para todos os outros tipos. Para SRV, coloque peso, porto e alvo no valor.

Exemplo de solicitação

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

Exemplo de resposta

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

Campo	Tipo	Descrição
`uuid`	string	Identificador de registo, utilizado pelos registos/endpoints /api/v1/dns
`priority`	integer \| null	Prioridade para os registros MX e SRV, caso contrário nulo
`created_at`	date	A data de criação só (A-MM-DD), sem tempo

Códigos de status de resposta

200	GET: os registos da zona
201	POST: registro criado
400	Erro de validação, por exemplo um tipo de registro desconhecido, um TTL faltante, ou um registro MX ou SRV sem prioridade
404	Não encontrado, ou pertence a outra conta

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

Republica uma zona

Puxa a zona e todos os seus registros para os servidores de nomes novamente. As alterações de registro são publicadas automaticamente, mas a publicação é o melhor esforço e um falha não falha o pedido original, então use isso quando uma mudança não aparece em buscas do DNS. Nenhum corpo de pedido é necessário.

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

PEGAR POST /api/v1/dns-records/

Listar ou criar registros através de zonas

O EGT devolve os registros de todas as suas zonas, 25 por página, ordenados por domínio, tipo e nome. O POST cria um registro como o ponto final dos registros de zona, mas toma a zona no corpo como zona_uuid.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`zone`	string	Não	Apenas registos da zona com este uuid
`record_type`	string	Não	Apenas registos deste tipo, por exemplo MX (caso insensível)
`page`	integer	Não	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 status de resposta

200	GET: sucesso
201	POST: registro criado
400	Erro de validação, ou zona_uuid está faltando ou não uma das suas zonas

PEGAR PUT PATCH EXCLUIR /api/v1/dns-records/{uuid}/

Obter, Atualizar ou Apagar um Registro

GET devolve um registro. PUT o substitui e precisa de registro_tipo, nome, valor e TTL. O PATCH só altera os campos que você envia. DELETE remove o registro e retorna 204 sem corpo. As alterações são publicadas imediatamente. Os registros NS criados com a zona são registros de sistema: atualizando ou excluindo os retorna 403.

Quando você PATCULAR a prioridade de um registro MX ou SRV, envie record_type no mesmo pedido. Um corpo PATCH com prioridade, mas sem record_type limpa a prioridade.

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 status de resposta

200	O registo
204	A resposta não tem corpo.
400	Erro de validação
403	O registro é um registro do sistema, ou o token carece da permissão requerida
404	Não encontrado, ou pertence a outra conta

Tratamento de Erros

Os erros de validação retornam 400 com o problema chaveado pelo nome do campo:

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

Teste de Alterações DNS

Consultar os servidores de nomes VPS.org diretamente para confirmar uma alteração é ao vivo antes de sua delegação de registro ou cache de resolvedores apurar:

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 gerenciamento de DNS

Visão geral

Listar todas as zonas DNS

Parâmetros de consulta

Exemplo de solicitação

Exemplo de resposta

Campos de resposta

Códigos de status de resposta

Criar uma Zona DNS

Parâmetros do corpo da requisição

Exemplo de resposta

Códigos de status de resposta

Obter detalhes da zona DNS

Códigos de status de resposta

Apagar a Zona DNS

Códigos de status de resposta

Listar ou adicionar registos numa zona

Parâmetros do corpo da requisição (POST)

Exemplo de solicitação

Exemplo de resposta

Campos de resposta

Códigos de status de resposta

Republica uma zona

Listar ou criar registros através de zonas

Parâmetros de consulta

Códigos de status de resposta

Obter, Atualizar ou Apagar um Registro

Códigos de status de resposta

Tratamento de Erros

Teste de Alterações DNS