Referência API
Use as operações API e interprete os seus resultados
Leia os endpoints disponíveis, regras de idempotência, respostas de ações em fila e limites atuais no rastreio de operações.
Nesta página
Antes de começar
- Uma sessão válida e, para alterações protegidas, o seu token CSRF.
- Identificadores retirados do catálogo atual ou de respostas autenticadas API.
- Uma Idempotency-Key única para cada encomenda, levantamento ou ação de hardware.
Leia a conta antes de a alterar
Utilize os endpoints de leitura para confirmar a conta, o saldo e o recurso de destino. GET /api/v1/me devolve o nome de utilizador, o balanceUsd e o csrfToken da sessão. Os identificadores de recursos são específicos da conta; utilize o identificador do servidor ou da rede devolvido para a conta atual em vez de copiar um valor de outro ambiente.
O API atual é uma interface de conta compacta, não uma plataforma completa de trabalhos assíncronos. Guarde as referências de escritas bem-sucedidas nos seus próprios registos. Não existe um endpoint para listar todas as encomendas, inspecionar uma ação específica em fila ou obter o estado de revisão mais recente de um levantamento.
| Ler endpoint | Dados devolvidos |
|---|---|
| GET /api/v1/ledger | As últimas entradas do livro-razão 100, mais recentes primeiro; sem contrato de paginação. |
| GET /api/v1/servers | Servidores não terminados, estado, região, paidThrough, graceUntil e autoRenew. |
| GET /api/v1/network | Endereços atribuídos, comprimentos de prefixo, valores PTR e identificadores de servidor relacionados. |
| GET /api/health | Contagens básicas de serviço e catálogo; sem garantia de saúde da conta ou do servidor físico. |
Use o ponto de extremidade de alteração correspondente
As ações de servidor suportadas são reiniciar, power_off, reinstalar, mount_iso, kvm e rotate_root_password. Um URL ISO personalizado deve utilizar HTTPS público sem credenciais incorporadas. O prazo do pedido é semanal ou mensal, representando sete ou trinta dias. O preço, os descontos, os fundos e a capacidade são verificados pelo serviço; não envie um preço calculado pelo cliente como autoridade.
| Ponto final | Campos do pedido e resultado |
|---|---|
| POST /api/v1/orders | configId, regionId, osId, term, quantity; opcional sshPublicKey. Devolve o id da encomenda e ACCEPTED. |
| POST /api/v1/deposit-addresses | ativo. Devolve endereço, ativo, rede, confirmationsRequired e modo, ou erro de liquidação indisponível. |
| POST /api/v1/withdrawals | ativo, destino, usd. Devolve id e PENDING_REVIEW; o saldo é retido. |
| POST /api/v1/servers/{id}/actions | ação; isoUrl para mount_iso. Devolve o ID da ação e QUEUED. |
| PUT /api/v1/servers/{id}/ddos | modo: BASELINE ou ADVANCED. Devolve QUEUED ou UNCHANGED e quoteRequired. |
| PUT /api/v1/network/{id}/rdns | ptr, ou um valor vazio para limpar. Devolve o valor PTR armazenado. |
Torne as tentativas deliberadas
Encomendas, levantamentos, ações de servidor e pedidos DDoS requerem Idempotency-Key. Use 8–100 letras, números, hífens ou underscores, e aloque uma nova chave para cada operação distinta pretendida. Preserve a chave original, o recurso e o payload antes de enviar para que uma resposta incerta possa ser investigada.
As encomendas podem reproduzir o resultado existente para a mesma chave e pedido normalizado; detalhes de encomenda alterados produzem um conflito. Repetições de ações de servidor devolvem a ação existente quando compatível. Mantenha as chaves de ação únicas em todos os servidores da conta. Levantamentos reportam um conflito quando já registados em vez de devolver o pedido original como sucesso.
POST /api/v1/servers/{serverId}/actions HTTP/1.1
Content-Type: application/json
x-csrf-token: <current-session-token>
Idempotency-Key: <unique-operation-key>
Cookie: <current-session-cookies>
{"action":"reboot"}Distinga aceitação de conclusão
Uma resposta EM FILA 202 confirma que um pedido de hardware foi registado. Não contém um URL KVM funcional, uma palavra-passe root de substituição ou prova de que a máquina reiniciou. Da mesma forma, ACEITE regista uma encomenda a entrar em aprovisionamento; PENDING_REVIEW regista um levantamento à espera de revisão do operador. Preserve o identificador devolvido ao perguntar sobre a execução.
Não há rota de consulta de estado de ação nesta versão. Releia os dados do servidor ou da rede quando relevante e obtenha confirmação do operador para efeitos físicos. Um PTR armazenado ou preferência DDoS por si só não é uma medição de DNS público ou proteção de rede em tempo real.
Responda a falhas sem duplicar trabalho
- Erro de validação 400: corrija os campos documentados antes de reenviar.
- 401 ou 403: repare a autenticação da sessão ou a verificação CSRF antes de tentar novamente.
- 404: verifique se o identificador do recurso pertence à conta com sessão iniciada.
- 409: inspecione o código de erro; saldo insuficiente, capacidade esgotada e conflitos de idempotência requerem respostas diferentes.
- 502 ou 503 em depósitos: não foi devolvido nenhum endereço novo utilizável; não inicie uma transferência.
- Tempo limite ou resposta ilegível: verifique os registos de conta disponíveis e preserve os detalhes do pedido original. Não crie cegamente uma nova chave de operação.