Démarrer avec l'API FFxF

L'API sert à faire depuis votre code ce que vous faites dans la console : commander une machine, l'allumer, la réinstaller, la détruire. Elle emprunte exactement le même chemin — mêmes quotas, même crédit, mêmes refus. Si la console vous dit non, l'API vous dira non, avec la même raison.

Ce guide va du compte vide à une machine qui tourne, en quatre appels.

1. Créer une clé

Dans la console, Compte → Clés d'API. Donnez-lui un nom qui dise à quoi elle sert (runners CI, supervision) et ne cochez que les portées dont cet outil a besoin. Une clé qui ne fait que surveiller n'a rien à faire avec le droit de détruire.

Le jeton s'affiche une seule fois. Nous n'en gardons que l'empreinte : perdu, il se révoque et se remplace, il ne se retrouve pas.

2. Le premier appel

Vérifiez la clé sur votre propre compte. C'est aussi la réponse à lire avant toute commande : elle dit ce que vous pouvez dépenser.

bash

curl -s https://api.ffxf.net/v1/account \
     -H "Authorization: Bearer $FFXF_TOKEN"

bash

{
  "data": {
    "currency": "CAD",
    "credit": { "balance": "124.60" },
    "hourly": { "burn_rate": "0.069", "runway_hours": 1805.8, "active_machines": 3 },
    "quota": { "limit": 5, "used": 3, "remaining": 2 }
  }
}

burn_rate est ce que votre parc consomme par heure, runway_hours le temps qu'il tiendra au solde actuel. Un script qui surveille ces deux nombres n'a jamais de mauvaise surprise.

3. Choisir dans le catalogue

Les régions, les forfaits et les images se lisent sans clé : vous pouvez écrire votre script avant même d'avoir un compte.

bash

curl -s https://api.ffxf.net/v1/images?plan=nano | jq '.data[].slug'

Le filtre ?plan= n'affiche que les images qui tiennent sur ce forfait : sur les 20 Go du Nano, un Windows qui en réclame 32 ne figure pas dans la liste, plutôt que d'échouer à la commande.

4. Commander une machine

Commencez par un essai à blanc. dry_run fait tourner tous les contrôles — quota, crédit, stock, compatibilité — et rend le prix, sans rien créer.

bash

curl -s https://api.ffxf.net/v1/vms \
     -H "Authorization: Bearer $FFXF_TOKEN" \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -d '{"plan":"nano","region":"montreal","image":"debian-13",
          "hostname":"runner-01","billing":"hourly","dry_run":true}'

bash

{
  "data": {
    "would_succeed": true,
    "hourly_rate": "0.018",
    "month_equivalent": "13.14",
    "required_credit": "0.44",
    "balance": "124.60",
    "runway_hours_after": 1428.0,
    "checks": [ { "name": "quota", "status": "pass" }, { "name": "credit", "status": "pass" } ]
  }
}

required_credit vaut ici 24 heures de consommation : c'est l'avance exigée pour ouvrir une location à l'heure. Retirez dry_run et la machine part en construction.

L'en-tête Idempotency-Key est obligatoire, et ce n'est pas une formalité : si votre requête expire sans réponse, la rejouer avec la même clé vous rend la première réponse au lieu de créer une seconde machine.

5. Suivre la construction

La réponse rend la machine et une action. Rien n'est instantané : le disque se clone, l'adresse se réserve, l'image démarre.

bash

curl -s https://api.ffxf.net/v1/actions/90112 \
     -H "Authorization: Bearer $FFXF_TOKEN" | jq .data.status

Sondez jusqu'à ce que le statut quitte running. En cas d'échec, l'action porte le motif — il n'y a pas à deviner dans les journaux.

6. Détruire

bash

curl -s -X DELETE "https://api.ffxf.net/v1/vms/4312?confirm=runner-01" \
     -H "Authorization: Bearer $FFXF_TOKEN"

Le nom d'hôte doit être recopié dans confirm. Un identifiant mal recollé dans une boucle détruirait la mauvaise machine, et un disque ne se rend pas. À l'heure, la suppression est immédiate et l'heure entamée reste due ; le compteur s'arrête avec la machine.