# 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](/openapi.json); prueba las llamadas en la [referencia interactiva](/docs/reference).

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

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

Devuelve los precios en tiempo real y la disponibilidad por familia de GPU.

## Alquilar una 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"}'
```

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.

Más: [toda la documentación](/es/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/es/llms.txt)