Gerencie seu VPS com a API REST e curl: status, energia, reinstalação, renovação

Pedir um servidor pela API leva uma requisição. Isso está em Peça um VPS em 4 chamadas de API. Esta página trata de tudo o que vem depois: as ações de rotina que você faria clicando no painel, escritas como comandos curl para colar num script.

Cada comando abaixo foi executado contra a nossa API antes da publicação, e as respostas são cópias resumidas do que voltou.

Preparação

Duas variáveis deixam os comandos curtos:

export API=https://api.eqvps.com/api/v1/eqvps
export EQVPS_TOKEN='paste-your-token-here'

O token vem de POST /auth/register ou de Settings → API tokens no painel. Deixe-o fora do histórico do shell se outras pessoas usam a máquina; ler de um arquivo com export EQVPS_TOKEN=$(cat ~/.eqvps_token) basta.

Encontre seus servidores

curl -s $API/services -H "Authorization: Bearer $EQVPS_TOKEN"

Cada item tem um id como 47HZ7YF. É o código de serviço que todas as outras chamadas usam. Depois, o quadro completo de um servidor:

curl -s $API/services/47HZ7YF -H "Authorization: Bearer $EQVPS_TOKEN"

{ "data": {
    "id": "47HZ7YF", "status": "active", "queued": false,
    "product": { "slug": "nano", "name": "Nano" },
    "specs": { "vcpu": 2, "memory_mb": 1024, "disk_gb": 15 },
    "hostname": "agent-box",
    "vm": { "state": "running", "uptime": 5340 },
    "access": { "method": "ssh", "host": "203.0.113.10", "port": 21521, "user": "root", "nat": true, ... } } }

access diz como entrar. Num plano com IPv4 próprio a porta é 22; num plano NAT é a sua porta encaminhada pessoal. Essa chamada só lê, então consultá-la em loop é seguro.

Se você pediu sem chave SSH, a senha de root aparece uma vez:

curl -s "$API/services/47HZ7YF?reveal=1" -H "Authorization: Bearer $EQVPS_TOKEN"

Enquanto o servidor ainda está iniciando, a resposta diz password_pending e a exibição única não é gasta. Espere meio minuto e pergunte de novo.

Energia: start, stop, reboot

curl -s -X POST $API/services/47HZ7YF/power \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"action": "reboot"}'

action é start, stop ou reboot. Um servidor que ainda não está ativo (ainda sendo criado, ou suspenso por falta de pagamento) responde 409 Service is not active. Não é erro do seu script. Verifique status antes.

Métricas

curl -s "$API/services/47HZ7YF/metrics?timeframe=day" -H "Authorization: Bearer $EQVPS_TOKEN"

CPU, memória, rede e disco como série temporal. timeframe é hour (padrão), day, week ou month. Bom para um cron que avisa quando o disco não para de crescer. Os contadores de tráfego do período de cobrança atual estão em Verificar velocidade e tráfego.

Renomear o servidor

curl -s -X POST $API/services/47HZ7YF/hostname \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"hostname": "web-01"}'

O novo nome é aplicado no sistema em execução pelo agente convidado, sem reiniciar no Linux. Se o servidor estiver parado, ou você removeu o qemu-guest-agent, a chamada retorna 409 agent_unavailable e nada muda.

Reinstalar o SO

Esta apaga o disco. A API exige que você digite o hostname atual do servidor em confirm, assim um script com id de serviço errado não apaga a máquina errada:

curl -s -X POST $API/services/47HZ7YF/reinstall \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"os_id": 4, "confirm": "web-01"}'

os_id vem da lista available_os do seu plano em GET /products ou dos detalhes do próprio servidor. A reinstalação roda em segundo plano; consulte GET /services/{id} até status voltar a ser active.

Renovação e saldo

Os servidores se renovam todo mês pelo seu saldo pré-pago. Para ver quanto custam prazos maiores para este servidor:

curl -s $API/services/47HZ7YF/renew-options -H "Authorization: Bearer $EQVPS_TOKEN"

Para pagar adiantado, digamos três meses, numa chamada:

curl -s -X POST $API/services/47HZ7YF/renew \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"months": 3}'

months é 1, 3, 6 ou 12, e 12 é cobrado pelo preço anual com o desconto. A resposta diz paid_from_balance: true e traz a nova data de vencimento. Se o saldo não cobrir o valor, nada é cobrado: você recebe paid_from_balance: false e uma checkout_url para essa fatura. Depois de recarregar o saldo, POST $API/invoices/{invoice_id}/pay paga essa fatura com o saldo; se ainda faltar, ele devolve o mesmo tipo de checkout_url e não cobra nada. Consultar e recarregar o saldo:

curl -s $API/balance -H "Authorization: Bearer $EQVPS_TOKEN"

curl -s -X POST $API/balance/topup \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"amount": 25}'

A resposta da recarga traz uma checkout_url. É um pagamento cripto: USDT, USDC ou ETH em Base, Ethereum ou Polygon. O saldo é creditado quando o pagamento é confirmado on-chain. Pagar é o único passo que um script não faz por você, a menos que tenha uma carteira.

Monero também funciona, mas só como recarga de saldo com verificação manual: você envia XMR, informa o id da transação e creditamos após verificar. Veja Pagar com Monero.

Cancelar, e mudar de ideia

O cancelamento seguro mantém o servidor rodando até o fim do período pago e simplesmente não renova:

curl -s -X POST $API/services/47HZ7YF/cancel \
  -H "Authorization: Bearer $EQVPS_TOKEN" -H "Content-Type: application/json" \
  -d '{"type": "end_of_period", "reason": "moving the project elsewhere"}'

reason é obrigatório. Poucas palavras bastam. Mudou de ideia antes da data?

curl -s -X POST $API/services/47HZ7YF/cancel/undo -H "Authorization: Bearer $EQVPS_TOKEN"

Também existe "type": "immediate". Ele apaga o servidor e os dados na hora, exige "confirm": "<hostname>" e não pode ser desfeito. A menos que seja para valer, use end_of_period.

Mantenha o token vivo

Tokens novos duram um ano por padrão. Toda resposta autenticada traz um cabeçalho X-Token-Expires-At, para que um script perceba cedo. Troque o token por um novo:

curl -s -X POST $API/auth/token/refresh -H "Authorization: Bearer $EQVPS_TOKEN"

O token antigo para de funcionar na hora, então salve o novo antes de fazer qualquer outra coisa.

Erros que vale tratar

Fazendo isso de um cliente de IA em vez de um script? As mesmas ações existem como ferramentas MCP — veja Como um agente cuida do próprio VPS via MCP e a referência da API. Ainda sem servidor? Escolha um plano.