Referência da API — provisione servidores com uma chamada

Início rápido

Um servidor, do zero, em duas chamadas.

Crie uma chave na área do cliente, escolha seus escopos, e ela é exibida uma única vez. Não há chave mestra nesta conta nem forma de ampliar uma chave depois — crie uma nova em vez disso.

1 — veja o que você pode comprar

curl -s https://api.dediprivacy.com/v1/plans?family=vps \
  -H "Authorization: Bearer $DP_KEY"

2 — implante

curl -s -X POST https://api.dediprivacy.com/v1/servers \
  -H "Authorization: Bearer $DP_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "plan":   "vps-4",
        "region": "ams",
        "image":  "debian-13",
        "cycle":  "12"
      }'

O provisionamento consome o saldo da conta. Uma chamada que o deixaria negativo falha com 402 e o valor exato em falta, em vez de construir meia máquina — não há estado parcialmente provisionado para limpar, e nenhuma fatura chega depois.

Convenções

As partes que são iguais em toda chamada, decididas uma vez para você nunca precisar consultar de novo.

URL base: https://api.dediprivacy.com/v1 Somente TLS, HTTP/2, e nenhuma porta não criptografada da qual redirecionar. Uma requisição em texto claro é recusada em vez de atualizada, porque uma atualização significa que a requisição já cruzou a rede uma vez.
Autenticação: Token bearer, por chave As chaves são criadas na área do cliente com os escopos que você escolher, exibidas uma única vez e armazenadas com hash. Não há chave mestra nem autenticação por senha nesta API.
Tipo de conteúdo: application/json Em requisições e respostas. Os horários são RFC 3339 em UTC, valores monetários são um número inteiro de centavos, e não há nenhum formato dependente de localidade.
Idempotência: Idempotency-Key em todo POST Uma chave repetida retorna a resposta original em vez de provisionar duas vezes. As chaves são lembradas por 24 horas, mais tempo do que qualquer loop de nova tentativa deveria durar.
Limite de taxa: 600 solicitações por minuto Por chave, retornado em X-RateLimit-Remaining. As chamadas de provisionamento têm limite separado de 60 por hora; avise se isso realmente atrapalhar você.
Paginação: Cursor, não número de página Um next_cursor em toda resposta de listagem. A paginação por offset pula linhas silenciosamente quando o conjunto subjacente muda, e preferimos não entregar esse bug a você.

Identificadores

Lido a partir do mesmo catálogo em que se baseiam as listas de preços públicas e o configurador. Uma região adicionada à estrutura aparece aqui sem que ninguém edite esta página.

região

kefReykjavík
otpBucareste
sofSófia
kivChișinău
zrhZurique
amsAmsterdã
ptyCidade do Panamá
sinCingapura

família

vpsVPS em nuvem
rdpWindows RDP
dedicadoServidores Dedicados
gpuGPU Compute
nuvem-privadaNuvem Privada
web-hostingHospedagem Web
armazenamentoArmazenamento de Objeto e Bloco
colocationColocation
personalizadoCompilação personalizada

ciclo

11 mês
33 mêss, −5 %
1212 mêss, −20 %
2424 mêss, −35 %

Endpoints

Catálogo

Tudo o que pode ser contratado, com preços em tempo real. Sem necessidade de autenticação — são os mesmos valores usados para montar as listas de preços públicas.

GET /regions Listar regiões

Cada região com seu identificador, cidade, país e estado operacional atual.

Resposta

{
  "data": [
    { "id": "ams", "city": "Amsterdam", "country": "Netherlands",
      "status": "operational", "uplink_gbit": 600 }
  ]
}

GET /plans Listar planos

Filtre por família com ?family=vps. Os preços são por mês em centavos, antes de qualquer desconto de ciclo.

Resposta

{
  "data": [
    { "id": "vps-4", "family": "vps", "cores": 4, "ram_gb": 8,
      "disk_gb": 160, "price_cents": 1100, "regions": ["ams","kef"] }
  ],
  "next_cursor": null
}

GET /images Listar imagens

Imagens de sistema operacional disponíveis por família, com a situação de licenciamento de cada uma.

Resposta

{
  "data": [
    { "id": "debian-13", "name": "Debian 13", "licence": "included" },
    { "id": "win-2025", "name": "Windows Server 2025", "licence": "included" }
  ]
}

Endpoints

Servidores

Crie, inspecione e controle máquinas. O provisionamento consome o saldo da conta; uma requisição que o deixaria negativo falha com 402 e o valor exato faltante, em vez de construir algo pela metade.

POST /servers Implantar um servidor

Retorna imediatamente com status "provisioning". Consulte o recurso periodicamente ou use um webhook.

Solicitação

{
  "plan": "vps-4",
  "region": "ams",
  "image": "debian-13",
  "cycle": "12",
  "label": "edge-01",
  "ssh_keys": ["ssh-ed25519 AAAA..."]
}

Resposta

{
  "id": "srv_8Kq2",
  "status": "provisioning",
  "region": "ams",
  "ipv4": null,
  "charged_cents": 10560,
  "renews_at": "2027-07-28T00:00:00Z"
}

GET /servers Listar servidores

Tudo na conta, dos mais recentes primeiro.

Resposta

{
  "data": [
    { "id": "srv_8Kq2", "label": "edge-01", "status": "active",
      "region": "ams", "ipv4": "203.0.113.10",
      "ipv6": "2001:db8:1234:5678::2" }
  ],
  "next_cursor": null
}

GET /servers/{id} Recuperar um servidor

Detalhamento completo, incluindo especificação, endereços e a próxima renovação.

Resposta

{
  "id": "srv_8Kq2",
  "status": "active",
  "plan": "vps-4",
  "image": "debian-13",
  "cycle": "12",
  "renews_at": "2027-07-28T00:00:00Z"
}

POST /servers/{id}/actions Agir em um servidor

Um endpoint, um campo de ação: reboot, shutdown, start, rebuild, resize, rdns.

Solicitação

{
  "action": "rebuild",
  "image": "ubuntu-26-04"
}

Resposta

{
  "id": "act_3Xf9",
  "action": "rebuild",
  "status": "running"
}

DELETE /servers/{id} Cancelar um servidor

Roda até o fim do período já pago. Passe ?immediate=true para destruí-lo agora e parar de pagar a partir de hoje.

Resposta

{
  "id": "srv_8Kq2",
  "status": "cancelled",
  "ends_at": "2027-07-28T00:00:00Z"
}

Endpoints

Faturamento

Um único saldo financia tudo. Não existe objeto de fatura porque não há nada a cobrar — um serviço debita do saldo na sua data de renovação.

GET /balance Consultar o saldo

Saldo atual, o que está comprometido com renovações, e quanto tempo isso dura no ritmo de consumo atual.

Resposta

{
  "balance_cents": 48250,
  "committed_cents": 12400,
  "runway_days": 117
}

POST /topups Abrir um recarregamento

Retorna um endereço de pagamento para o ativo escolhido. Qualquer bônus é aplicado no momento em que o pagamento é confirmado.

Solicitação

{
  "amount_cents": 100000,
  "asset": "XMR"
}

Resposta

{
  "id": "top_5Wc1",
  "asset": "XMR",
  "address": "4A...",
  "amount": "3.417",
  "bonus_cents": 30000,
  "expires_at": "2026-07-28T18:00:00Z"
}

GET /ledger Listar lançamentos do extrato

Todo crédito e débito, com o serviço a que cada um se refere. Isso é tudo o que mantemos sobre seus pagamentos.

Resposta

{
  "data": [
    { "at": "2026-07-28T16:04:00Z", "cents": -1100,
      "kind": "renewal", "ref": "srv_8Kq2" }
  ]
}

Endpoints

Status

Público e sem autenticação, para que possa ser consultado por algo que não tem sua chave — e para que continue respondendo mesmo se o problema for na sua conta.

GET /status Estado atual

Os mesmos números da página de status, calculados a partir do mesmo registro de incidentes.

Resposta

{
  "state": "operational",
  "open_incidents": 0,
  "uptime_90d": 99.9971,
  "regions": { "ams": "operational", "kef": "operational" }
}

GET /incidents Listar incidentes

O próprio registro, filtrável por região e data.

Resposta

{
  "data": [
    { "id": "inc_71", "region": "otp", "severity": "partial",
      "started_at": "2026-06-07T02:14:00Z",
      "unreachable_seconds": 1080 }
  ]
}

Erros

Toda falha carrega um estável código e uma mensagem escrita para uma pessoa. Corresponda ao código; a mensagem pode melhorar.

400 invalid_request O corpo não pôde ser interpretado, ou um campo está com o tipo errado. A mensagem indica o campo.

401 não autenticado Nenhuma chave, uma chave malformada, ou uma chave revogada.

403 scope_missing A chave é válida, mas não foi criada com o escopo que esta chamada exige. Os escopos são definidos por chave e não podem ser ampliados depois.

402 insufficient_funds O saldo não cobriria isso. A resposta traz required_cents e balance_cents para que você possa agir sem uma segunda chamada.

404 not_found Nenhum recurso encontrado nesta conta. Propositalmente idêntica à resposta para um recurso de outra conta.

409 conflito O recurso está ocupado — geralmente uma ação já em execução nesse servidor.

422 indisponível Válido, mas atualmente não é possível: o plano está fora de estoque nessa região, ou a imagem não é oferecida para essa família.

429 rate_limited O Retry-After é definido, e é preciso em vez de um valor constante.

5xx server_error Nosso. Seguro para repetir com a mesma Idempotency-Key — é exatamente para isso que ela serve.

A 404 para um recurso na conta de outra pessoa é, byte a byte, igual a uma resposta para um recurso que nunca existiu. Isso é proposital: respostas distinguíveis transformam uma API em um oráculo para enumerar a infraestrutura de outras pessoas.

API de hospedagemTudo o que o configurador faz, via HTTP.