Démarrer en cinq minutes

1. Créer une clé

Tableau de bord, Compte > Clés d'API, bouton Créer la clé.

1. Nommez-la d'après ce qui va l'utiliser : backup-cron, tableau-de-statut. 64 caractères au plus, sans < ni >.
2. Cochez les permissions. Pour cet essai : account:read, services:read, services.metrics:read.
3. Laissez le reste par défaut : tous les services, toute adresse, pas d'expiration.
4. Confirmez que c'est bien vous : code de double authentification, mot de passe, ou code envoyé par e-mail selon ce que porte votre compte.

Le secret s'affiche une seule fois : fpk_ suivi de 43 caractères. Copiez-le. Personne ne peut le relire ; en cas de perte, renouvelez la clé.

2. Faire un premier appel

export FRESHPERF_KEY="fpk_9al41uPRzeglnYvHa3YfvsK86OfQwx6BmC2EKmI0Vhw"

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     https://api.freshperf.fr/v1/me

{
  "data": {
    "account": {
      "id": 1234,
      "email": "[email protected]",
      "firstName": "Alex",
      "lastName": "Martin",
      "company": false,
      "companyName": null,
      "country": "FR",
      "createdAt": 1785104280762,
      "emailVerified": true,
      "twoFactorEnabled": true
    },
    "key": {
      "id": 2,
      "label": "tableau-de-statut",
      "keyPrefix": "fpk_9al41uPR",
      "scopes": ["account:read", "services:read", "services.metrics:read"],
      "allServices": true,
      "serviceCodes": [],
      "ipAllowlist": [],
      "expiresAt": null,
      "spendingCapCents": null,
      "spendingRemainingCents": null
    }
  }
}

GET /me dit pour qui la clé agit et ce qu'elle porte. C'est le premier appel à faire quand un script se comporte mal. Le contrat complet des champs est dans Tickets, clés SSH et compte.

3. Lister vos services

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     "https://api.freshperf.fr/v1/services?limit=5"

{
  "data": [
    {
      "code": "SRV-TJUAQ1-1951",
      "name": "Minecraft 1",
      "customName": null,
      "productShortname": "minecraft-1",
      "productTitle": "Minecraft 1",
      "category": "minecraft",
      "status": "ACTIVE",
      "providerType": "pterodactyl",
      "autoRenew": true,
      "nextBillingAt": 1789437385056,
      "recurrence": "monthly",
      "createdAt": 1786845385066,
      "activatedAt": 1786845385056
    }
  ],
  "pagination": { "nextCursor": null, "limit": 5 }
}

Le code est l'identifiant à utiliser dans toutes les routes de service.

curl -H "Authorization: Bearer $FRESHPERF_KEY" \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951/status

{
  "data": {
    "status": "running",
    "uptimeSeconds": 1450617,
    "cpu": 0.01823,
    "memoryBytes": 906903552,
    "memoryMaxBytes": 2147483648,
    "ipv4": "203.0.113.32:20018"
  }
}

4. Agir dessus

Agir demande une permission d'écriture. Modifiez la clé, ajoutez services.power:write, enregistrez, puis :

curl -X POST \
     -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -d '{"action": "restart"}' \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951/power

{ "data": { "status": "SUCCESS", "message": "Power signal accepted" } }

PENDING au lieu de SUCCESS veut dire que l'infrastructure y travaille encore : relisez /status quelques secondes plus tard.

5. Consulter le journal

Rouvrez la clé dans Compte > Clés d'API. Chaque appel que vous venez de faire y figure avec sa route, son statut, son adresse, sa durée et son X-Request-Id. Les refus aussi.

Ensuite