# 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](/openapi.json); teste chamadas na [referência interativa](/docs/reference).

## 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

```sh
curl $ARRAKIS_URL/v1/market/summary
```

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

## Alugue uma máquina

```sh
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.

Mais: [toda a documentação](/pt/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/pt/llms.txt)