Crie um token de API e faça a primeira chamada

Crie um token com o menor escopo possível

Os tokens são criados no painel, na conta, e carregam escopos: read, write, billing. Um token com write pode encomendar servidores, ou seja, um token vazado custa dinheiro. Dê a um script de monitoramento read e nada mais.

Duas configurações que valem a pena usar enquanto você está lá: uma data de expiração e uma restrição de origem que fixa o token ao prefixo de onde sua automação roda. Ambas são opcionais. Ambas são baratas.

O valor é mostrado uma única vez, porque armazenamos um hash dele, não o token. Perdê-lo significa criar outro.

export Paragon_TOKEN=...

Melhor que o histórico do shell, em uma máquina que roda sem supervisão:

systemd-creds encrypt token.txt /etc/credstore.encrypted/paragon-token

A primeira chamada

curl -s https://paragonvps.com/api/v1/account -H "Authorization: Bearer $Paragon_TOKEN" | jq .

Tudo é JSON, tudo fica sob /api/v1, e cada resposta traz um cabeçalho request_id. Cite isso em um ticket e encontramos a chamada exata em segundos, em vez de perguntar que horas eram.

curl -s https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" | jq -r '.[] | .id + " " + .hostname + " " + .site + " " + .state'

Encomendando um

curl -s -X POST https://paragonvps.com/api/v1/instances -H "Authorization: Bearer $Paragon_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: 2026-07-16-edge-01" -d '{"plan":"r-8","site":"AMS-01","image":"debian-13","hostname":"edge-01","ssh_keys":["primary"]}'

Envie o cabeçalho Idempotency-Key. Repetir um POST sem ele é como as pessoas acabam com dois servidores e uma intenção; a chave é lembrada por vinte e quatro horas e retorna o resultado original em vez de criar uma segunda instância. Os dados cloud-init do usuário vão no mesmo corpo, codificados em base64, sob user_data_b64.

Um pedido usa o saldo da sua conta quando o saldo cobre o primeiro ciclo. Caso contrário, a resposta traz uma fatura e um endereço de pagamento, e a instância aparece assim que a fatura é liquidada.

Limites de taxa e erros

Seiscentas requisições por minuto por token. Se você ultrapassar, recebe um 429 com um cabeçalho Retry-After, que está lá para ser lido em vez de substituído por um sleep fixo em um loop.

Erros são JSON com um code, um message legível e o request_id. O status indica a classe: 400 você enviou algo errado, 401 o token é inválido ou revogado, 403 o token não tem o escopo necessário, 404 não existe ou não é seu, 409 a instância está em um estado que não permite isso, e 5xx é nosso.

Paginação e polling

Coleções aceitam ?page= e ?per_page= e retornam um cabeçalho Link. Operações longas entregam um job em vez de bloquear, o que cobre provisionamento, migração e restauração:

curl -s https://paragonvps.com/api/v1/jobs/<job-id> -H "Authorization: Bearer $Paragon_TOKEN" | jq -r .state

Faça polling a cada poucos segundos, ou registre um webhook e pare de fazer polling de vez. Webhooks são assinados; verifique a assinatura antes de agir com base neles.

Revogação

Instantânea, pelo painel ou com outro token:

curl -s -X DELETE https://paragonvps.com/api/v1/tokens/<token-id> -H "Authorization: Bearer $Paragon_TOKEN"

Requisições em andamento terminam e a próxima recebe um 401. Se você suspeitar que um token vazou, revogue primeiro e investigue depois. Um token não pode mudar o e-mail da sua conta nem seu segundo fator, mas certamente pode gastar dinheiro.

A referência completa, todos os endpoints e todos os campos, está em /docs/api.