API

Autentique-se com um token e depois busque, alugue, gerencie e pague com JSON simples.

Noções básicas

URL base: $ARRAKIS_URL. Todas as requisições e respostas são em JSON.
Autentique-se com Authorization: Bearer ark_.... O token define a conta.
Os erros vêm como {"detail": "..."}, com um status que indica a causa: 401 (token), 402 (saldo ou limite de gastos), 403 (escopo), 404, 409, 422 (entrada), 429 (vá mais devagar), 503 (o aluguel ainda não abriu).
O esquema completo está em /openapi.json; teste chamadas na referência interativa.

Tokens e escopos

Escopo	Permite
`read`	Buscar máquinas; ver suas máquinas, volumes e imagens
`rent`	Alugar, reiniciar e parar máquinas
`manage`	Criar e revogar tokens; salvar chaves SSH e imagens
`billing`	Saldo, pagamentos, recarga automática, parada de emergência

Crie tokens em API & agents ou com POST /v1/tokens. Um token pode ter spend_limit_usd, max_rental_hours e expires_at. Um token só cria tokens com escopos que ele tem e dentro dos próprios limites.

Sem token

Shell

curl $ARRAKIS_URL/v1/market/summary

Retorna preços e disponibilidade em tempo real por família de GPU.

Alugue uma máquina

Shell

curl -X POST $ARRAKIS_URL/v1/instances \
  -H "Authorization: Bearer $ARRAKIS_TOKEN" -H "Content-Type: application/json" \
  -d '{"node_id": "<node>", "name": "eval", "ssh_public_key": "ssh-ed25519 AAAA...",
       "termination_hours": 4, "idempotency_key": "eval-2026-10-14"}'

Encontre um node_id com GET /v1/gpus; o tier dele indica on_demand ou spot. O saldo precisa cobrir a primeira hora (senão, 402), que é cobrada quando a máquina começa a rodar (mínimo de 1 hora). Envie max_price_per_gpu_hour para alugar por no máximo o preço que você viu (GET /v1/gpus/{node_id}/price): se o preço ao vivo for maior, nada é alugado e a resposta é 409.

Principais rotas

Método	Caminho	O que faz
GET	`/v1/market/summary`	Preços em tempo real por família de GPU (rota pública)
GET	`/v1/market/history`	Preços por hora de cada família de GPU, em JSON ou em CSV com `format=csv` (público)
GET	`/v1/models/fit?model=owner/name`	A memória de GPU que um modelo do Hugging Face precisa e as GPUs mais baratas que o comportam agora (público)
GET	`/v1/gpus`	Máquinas que você pode alugar, da mais barata para a mais cara
GET	`/v1/gpus/{node_id}/price`	O preço ao vivo de uma máquina agora
POST	`/v1/instances`	Alugue uma máquina
GET	`/v1/instances`, `/v1/instances/{id}`	Suas máquinas
POST	`/v1/instances/{id}/terminate`	Desligar e remover uma máquina
POST	`/v1/instances/{id}/schedule-removal`	Definir quando a máquina se remove sozinha
GET / POST / DELETE	`/v1/volumes`	Seus volumes: o que guardam, quanto custam, onde estão montados
GET	`/v1/billing/account`	Saldo, gasto por hora e quando o dinheiro acaba
POST	`/v1/billing/checkout`	Iniciar um pagamento com cartão, Link ou Apple Pay
POST	`/v1/billing/stop`	Parar tudo e pausar os aluguéis
GET / POST / DELETE	`/v1/tokens`	Listar, criar e revogar tokens
GET	`/v1/support/cases`	Seus casos de suporte e nossas respostas
POST	`/mcp`	MCP para agentes

Novas tentativas

Envie a mesma idempotency_key ao repetir um aluguel: você recebe a mesma máquina de volta, nunca uma segunda.

É um agente? Esta página em Markdown.