# API

Authentifiez-vous avec un jeton, puis cherchez, louez, gérez et payez en JSON simple.

## L’essentiel

- URL de base : `$ARRAKIS_URL`. Chaque requête et chaque réponse sont en JSON.
- Authentifiez-vous avec `Authorization: Bearer ark_...`. C’est le jeton qui détermine le compte.
- Les erreurs prennent la forme `{"detail": "..."}` avec un code de statut explicite : 401 (jeton), 402 (solde ou plafond de dépenses), 403 (portée), 404, 409, 422 (paramètres), 429 (ralentissez), 503 (la location n’est pas encore ouverte).
- Le schéma complet est [/openapi.json](/openapi.json) ; essayez les appels dans la [référence interactive](/docs/reference).

## Jetons et portées

| Portée | Autorise |
|---|---|
| `read` | Chercher des machines ; consulter vos machines, volumes et images |
| `rent` | Louer, redémarrer et arrêter des machines |
| `manage` | Créer et révoquer des jetons ; enregistrer des clés SSH et des images |
| `billing` | Solde, paiements, recharge automatique, arrêt d’urgence |

Créez des jetons dans **API & agents** ou avec `POST /v1/tokens`. Un jeton peut porter `spend_limit_usd`, `max_rental_hours` et `expires_at`. Un jeton ne peut créer que des jetons dotés de portées qu’il possède, dans la limite de ses propres plafonds.

## Sans jeton

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

Renvoie les prix en temps réel et la disponibilité par famille de GPU.

## Louer une machine

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

Trouvez un `node_id` avec `GET /v1/gpus` ; son `tier` indique `on_demand` ou `spot`. Le solde doit couvrir la première heure (sinon 402), facturée quand la machine démarre (minimum 1 heure). Envoyez `max_price_per_gpu_hour` pour louer au plus au prix que vous avez vu (`GET /v1/gpus/{node_id}/price`) : si le prix en direct est plus élevé, rien n’est loué et la réponse est 409.

## Routes principales

| Méthode | Chemin | Ce qu’il fait |
|---|---|---|
| GET | `/v1/market/summary` | Prix en temps réel par famille de GPU (public) |
| GET | `/v1/market/history` | Les prix heure par heure de chaque famille de GPU, en JSON ou en CSV avec `format=csv` (public) |
| GET | `/v1/models/fit?model=owner/name` | La mémoire GPU dont un modèle de Hugging Face a besoin et les GPU les moins chers qui le contiennent en ce moment (public) |
| GET | `/v1/gpus` | Les machines que vous pouvez louer, les moins chères d’abord |
| GET | `/v1/gpus/{node_id}/price` | Le prix en direct d’une machine maintenant |
| POST | `/v1/instances` | Louer une machine |
| GET | `/v1/instances`, `/v1/instances/{id}` | Vos machines |
| POST | `/v1/instances/{id}/terminate` | Arrêter et supprimer une machine |
| POST | `/v1/instances/{id}/schedule-removal` | Fixer l’heure de suppression automatique |
| GET / POST / DELETE | `/v1/volumes` | Vos volumes : ce qu’ils contiennent, ce qu’ils coûtent, où ils sont montés |
| GET | `/v1/billing/account` | Solde, rythme de dépense, date d’épuisement des fonds |
| POST | `/v1/billing/checkout` | Lancer un paiement par carte, Link ou Apple Pay |
| POST | `/v1/billing/stop` | Tout arrêter et suspendre les locations |
| GET / POST / DELETE | `/v1/tokens` | Lister, créer et révoquer des jetons |
| GET | `/v1/support/cases` | Vos demandes d’assistance et nos réponses |
| POST | `/mcp` | MCP pour les agents |

## Nouvelles tentatives

Envoyez la même `idempotency_key` quand vous relancez une location : vous récupérez la même machine, jamais une deuxième.

Plus : [toute la documentation](/fr/docs.md) · [OpenAPI](/openapi.json) · [llms.txt](/fr/llms.txt)