Um token, criado no painel do cliente
Enviado como um bearer token. Pode ser restrito a somente leitura ou a um único serviço; os tokens são independentes da senha, e revogar um deles nunca encerra a sessão.
Um token, e tudo o que o painel pode fazer
JSON sobre HTTPS. Nenhum SDK necessário, nenhuma conta de desenvolvedor separada, e nenhum endpoint que exista no painel mas não aqui.
Criar um servidor
curl -X POST https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-d '{"plan":"reef","image":"debian-13"}'Retorna um build id imediatamente. A máquina responde por SSH cerca de sessenta segundos depois, e o endereço já está roteado antes de as credenciais serem enviadas.
20 endpoints
Tudo, em cinco grupos
URL Base https://api.vpsoffshore.com/v1. Versionado no caminho; a v1 continuará funcionando quando a v2 existir, e a data em que deixar de funcionar será anunciada com um ano de antecedência.
Servidores
GET
/servers
Todos os serviços da conta, com estado, plano e endereços.
POST
/servers
Crie um. Retorna imediatamente com um ID de build; o servidor fica acessível cerca de um minuto depois.
GET
/servers/{id}
Um serviço, incluindo o uso de recursos em tempo real na última hora.
PATCH
/servers/{id}
Mudar de plano. Redimensiona sem reconstruir, quando o disco permite.
DELETE
/servers/{id}
Destruímos. Os discos são mantidos por 14 dias e depois apagados antes da reemissão.
POST
/servers/{id}/actions
reiniciar · desligar · iniciar · reconstruir · recuperar · redefinir senha.
Armazenamento
GET
/servers/{id}/snapshots
Snapshots de um serviço, dos mais recentes para os mais antigos.
POST
/servers/{id}/snapshots
Tire um. Fino, portanto rápido e que não dobra o uso do disco.
POST
/snapshots/{id}/restore
Restauração no local, ou em outro serviço do mesmo plano ou superior.
DELETE
/snapshots/{id}
Remover um snapshot.
Rede
GET
/servers/{id}/addresses
Endereços roteados para um serviço, v4 e v6.
POST
/servers/{id}/addresses
Solicitar um endereço adicional, ou um /29.
PUT
/addresses/{ip}/rdns
Configure o DNS reverso. Tem efeito em até um minuto, não na próxima atualização de zona.
GET
/servers/{id}/bandwidth
Contadores de transferência. Informativo — não há limite a ser excedido.
Catálogo
GET
/plans
Todos os planos, com especificação e preço. A mesma fonte a partir da qual este site é gerado.
GET
/images
Imagens e ISOs disponíveis, incluindo as enviadas pelo cliente.
POST
/images
Envie uma ISO por URL. Inicializa com console conectado.
Faturamento
GET
/invoices
Faturas, pagas e em aberto, com a moeda e a transação na blockchain.
POST
/invoices/{id}/pay
Emite um endereço de pagamento para uma das 8 moedas aceitas.
GET
/credits
Créditos de SLA aplicados, com o incidente que gerou cada um.
Tudo o que o painel pode fazer está aqui, e nada aqui está ausente do painel. Quando os dois divergem, isso é um bug — avise pelo painel e ele é corrigido em vez de documentado como comportamento esperado.
Como se comporta
Quatro decisões perceptíveis em até uma hora
Uma API é julgada pelos seus caminhos ruins, não pelos bons. Três dos quatro itens abaixo tratam do que acontece quando algo dá errado.
JSON na entrada, JSON na saída, sem necessidade de SDK
HTTPS simples, sem envelope personalizado, sem fallback em XML e sem ritual de assinatura. Se o curl consegue fazer, já existe um cliente pronto. Bibliotecas oficiais existem para Go, Python e TypeScript, e nenhuma delas é obrigatória.
Limites de taxa que não são atingidos por acidente
600 requisições por minuto por token, 60 para chamadas de criação. Cada resposta traz o orçamento restante em um cabeçalho, e ultrapassá-lo retorna 429 com o número de segundos a aguardar — nunca uma queda silenciosa.
Erros que dizem o que fazer
Um 4xx traz um código legível por máquina, uma frase em linguagem natural e o campo com o problema. Preferimos retornar um erro longo a um erro curto que exige adivinhação.
As duas coisas escritas uma única vez
Autenticação, e a aparência de um erro
Vale a pena ler os dois antes da primeira chamada, e não depois da primeira falha.
Autenticar
curl https://api.vpsoffshore.com/v1/servers \
-H "Authorization: Bearer $TOKEN"Os tokens são criados no painel e podem ser restritos a somente leitura ou a um único serviço. Eles são independentes da senha, e revogar um deles não encerra a sessão em nenhum lugar.
Ler o limite de taxa
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 41Em toda resposta, não apenas na que falha. Exceder o limite retorna 429 com os segundos de espera, nunca um descarte silencioso e nunca uma resposta reduzida.
Um erro indica o campo
{"error":"plan_unknown",
"message":"No plan named 'reff'. Did you mean 'reef'?",
"field":"plan"}Um código legível por máquina, uma frase em linguagem humana e o campo responsável pelo erro. Erros longos saem mais baratos do que erros curtos que é preciso adivinhar.
Consultar uma configuração
curl https://api.vpsoffshore.com/v1/servers/$ID \
-H "Authorization: Bearer $TOKEN" | jq .statePassa de building para running. Não é preciso registrar nenhum webhook antes de criar o que quer que seja, e fazer polling uma vez por segundo está dentro do limite.
Nada a solicitar
O token está no painel do cliente, que já vem com o primeiro servidor
Nenhuma conta de desenvolvedor, nenhuma aprovação, nenhum sandbox que se comporte de forma diferente da produção.