Desenvolvedores
Referência da API
Autentique-se com uma sessão ou chave de API e use os endpoints implementados de conta, cotação, instância e cobrança.
8 min de leitura · AtualizadoAutenticação
O caminho base é /api/v1. As solicitações do navegador usam o cookie de sessão HttpOnly criado no login. Scripts podem usar Authorization: Bearer seguido de uma chave API ativa. As chaves têm permissões totais da conta e são exibidas uma única vez quando criadas.
A interface local usa chaves gh_demo_. Revogar uma chave impede imediatamente novas solicitações autenticadas que a utilizem. Não coloque chaves em URLs ou pacotes do lado do navegador.
GET /api/v1/balance
Authorization: Bearer <your-api-key>
200 OK
{ "currency": "USD", "balanceCents": 50000, "derivedFrom": "ledger_entries" }Regras de solicitação e repetição
Os corpos de POST e PATCH são objetos JSON, com Content-Type: application/json. Envie {} para ações sem parâmetros. Os corpos são limitados a 32 KiB de texto. As respostas usam Cache-Control: no-store.
Implantação, renovação manual e retirada exigem um Idempotency-Key de 8–128 caracteres. Use uma nova chave para uma nova operação pretendida e reutilize a mesma chave para sua repetição. Nunca a reutilize com um corpo diferente. Uma resposta de repetição inclui replayed: true.
As cotações de instância calculam o preço atual do catálogo sem reservar capacidade. Envie expectedPriceCents ao implantar; uma incompatibilidade retorna 409 para que o preço possa ser revisado novamente.
POST /api/v1/instances
Content-Type: application/json
Idempotency-Key: <unique-operation-id>
Authorization: Bearer <your-api-key>
{
"sku": "nvidia-rtx-4090",
"gpuCount": 1,
"region": "dal",
"image": "pytorch",
"period": "week",
"options": [],
"sshKeyId": "<saved-key-id>",
"autoRenew": false,
"expectedPriceCents": 11000
}Endpoints implementados
Todos os recursos da conta são restritos ao seu proprietário. O endpoint de disponibilidade é público e expõe o snapshot do catálogo, não uma sondagem de hardware ao vivo.
| Método | Caminho após /api/v1 | Finalidade |
|---|---|---|
| POST | /auth/register · /auth/login | Nome de usuário + senha; criar uma sessão |
| POST | /auth/recover | Nome de usuário + código não utilizado + nova senha |
| POST | /auth/logout | Revogar a sessão atual do navegador |
| GET | /me · /balance · /ledger | Conta, saldo e últimas 100 entradas |
| GET / DELETE | /sessions · /sessions/:id | Listar sessões ativas ou revogar uma |
| GET | /availability | Catálogo público e instantâneo regional de estoque |
| GET / POST | /deposit-quotes | Liste cotações ativas ou crie uma com asset + desiredUsdCents |
| POST | /demo/confirm-deposit | ID do orçamento; somente desenvolvimento local |
| GET | /deposits · /withdrawals | Últimos 100 registos desta conta |
| POST | /withdrawals | Ativo + destino + amountUsdCents; idempotente |
| POST | /instance-quotes | GPU, quantidade, região, imagem, período e opções |
| GET / POST | /instances | Liste alocações ou implante; a implantação é idempotente |
| POST | /instances/:id/start · stop · release · renew | Ação de ciclo de vida; a renovação é idempotente |
| PATCH | /instances/:id/auto-renew | Defina enabled como true ou false |
| GET / POST | /ssh-keys · /api-keys | Listar ou criar chaves da conta |
| DELETE | /ssh-keys/:id · /api-keys/:id | Revogar uma chave |
Trate erros explicitamente
Erros têm {error, message}: um código estável e uma explicação legível. 400 indica entrada inválida, 401 autenticação ausente ou inválida, 403 origem rejeitada, 404 recurso desconhecido ou sem proprietário, 409 conflito de saldo/state/duplicate e 415 tipo de conteúdo incorreto.
Para uma cotação de depósito expirada, crie outra cotação. Para um estado de instância alterado, recarregue a instância antes de decidir sobre outra ação. Após uma interrupção de rede, reutilize a chave da operação em vez de criar uma segunda cobrança.