API
Autentícate con un token y luego busca, alquila, gestiona y paga con JSON sencillo.
Conceptos básicos
- URL base:
$ARRAKIS_URL. Todas las solicitudes y respuestas son JSON. - Autentícate con
Authorization: Bearer ark_.... El token determina la cuenta. - Los errores son
{"detail": "..."}con un código de estado significativo: 401 (token), 402 (saldo o límite de gasto), 403 (alcance), 404, 409, 422 (entrada), 429 (reduce el ritmo), 503 (el alquiler aún no está abierto). - El esquema completo está en /openapi.json; prueba las llamadas en la referencia interactiva.
Tokens y alcances
| Alcance | Permite |
|---|---|
read | Buscar máquinas; consultar tus máquinas, volúmenes e imágenes |
rent | Alquilar, reiniciar y detener máquinas |
manage | Crear y revocar tokens; guardar claves SSH e imágenes |
billing | Saldo, pagos, recarga automática, parada de emergencia |
Crea tokens en API & agents o con POST /v1/tokens. Un token puede llevar spend_limit_usd, max_rental_hours y expires_at. Un token solo puede crear tokens con alcances que tenga, dentro de sus propios límites.
Sin token
curl $ARRAKIS_URL/v1/market/summaryDevuelve los precios en tiempo real y la disponibilidad por familia de GPU.
Alquilar una máquina
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"}'Busca un node_id con GET /v1/gpus; su tier indica on_demand o spot. El saldo debe cubrir la primera hora (si no, 402), que se cobra cuando la máquina empieza a funcionar (mínimo de 1 hora). Envía max_price_per_gpu_hour para alquilar como máximo al precio que viste (GET /v1/gpus/{node_id}/price): si el precio en vivo es más alto, no se alquila nada y recibes 409.
Rutas principales
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /v1/market/summary | Precios en tiempo real por familia de GPU (endpoint público) |
| GET | /v1/market/history | Precios por hora de cada familia de GPU, en JSON o en CSV con format=csv (público) |
| GET | /v1/models/fit?model=owner/name | La memoria de GPU que necesita un modelo de Hugging Face y las GPU más baratas que lo sostienen ahora (público) |
| GET | /v1/gpus | Máquinas que puedes alquilar, de la más barata a la más cara |
| GET | /v1/gpus/{node_id}/price | El precio en vivo de una máquina ahora |
| POST | /v1/instances | Alquilar una máquina |
| GET | /v1/instances, /v1/instances/{id} | Tus máquinas |
| POST | /v1/instances/{id}/terminate | Detener y eliminar una máquina |
| POST | /v1/instances/{id}/schedule-removal | Fijar cuándo se elimina sola |
| GET / POST / DELETE | /v1/volumes | Tus volúmenes: qué guardan, cuánto cuestan, dónde están montados |
| GET | /v1/billing/account | Saldo, ritmo de gasto y cuándo se acaba el dinero |
| POST | /v1/billing/checkout | Iniciar un pago con tarjeta, Link o Apple Pay |
| POST | /v1/billing/stop | Detener todo y pausar los alquileres |
| GET / POST / DELETE | /v1/tokens | Listar, crear y revocar tokens |
| GET | /v1/support/cases | Tus casos de soporte y nuestras respuestas |
| POST | /mcp | MCP para agentes |
Reintentos
Envía la misma idempotency_key cuando reintentes un alquiler: recibes la misma máquina, nunca una segunda.
¿Eres un agente? Esta página en Markdown.