Gérer vos services

Toutes les routes de cette page prennent le code du service (SRV-TJUAQ1-1951), donné par GET /services. Un service hors de la restriction de la clé répond 404 SERVICE_NOT_FOUND.

GET /services

Permissions : services:read

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

{
  "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": 2 }
}

GET /services/{code}

Permissions : services:read

Reprend les champs ci-dessus et ajoute :

{
  "data": {
    "code": "SRV-TIYMZT-8349",
    "name": "VPS 1",
    "status": "ACTIVE",
    "providerType": "vps",
    "provisioned": true,
    "autoRenew": true,
    "nextBillingAt": 1787960297645,
    "recurrence": "monthly",
    "priceCents": 500,
    "taxCents": 100,
    "currency": "EUR",
    "dunningState": "NONE",
    "restartRequired": false,
    "restartRequiredReason": null,
    "configuration": {
      "os": "debian", "osVersion": "13", "location": "paris",
      "cpuCores": "2", "ramSize": "2048", "diskSize": "20"
    },
    "cancelledAt": null
  }
}

GET /services/{code}/status

Permissions : services.metrics:read

Interroge l'infrastructure en direct. Comptez jusqu'à deux secondes de latence.

Tous les champs peuvent valoir null : chaque fournisseur remonte ce qu'il connaît.

INSTANCE_NOT_PROVISIONED (409) tant que l'infrastructure n'existe pas.

GET /services/{code}/metrics/history

Permissions : services.metrics:read

{ "data": { "samples": [
  { "ts": 1787903520000, "cpu": 0.1364, "mem": 1069400678, "maxmem": 2147483648, "netin": 4550, "netout": 69 }
] } }

samples est un tableau d'objets libres : la fenêtre, le pas et les clés viennent du fournisseur. Le tableau est vide quand aucun historique n'est disponible, notamment sur les serveurs de jeu.

POST /services/{code}/power

Permissions : services.power:write Débit : 20 par minute, par clé et par service.

kill n'existe que sur les serveurs de jeu ; sur un VPS il répond 400 ACTION_UNSUPPORTED.

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

Sur PENDING, relisez /status toutes les 5 à 10 secondes.

POST /services/{code}/console/command

Permissions : services.console:write

Serveurs de jeu uniquement.

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

{ "data": { "status": "SUCCESS", "message": "Command sent" } }

Sur un VPS : 400 ACTION_UNSUPPORTED. Sur un serveur arrêté, le panneau refuse la commande et la réponse est 502 ACTION_FAILED.

Sauvegardes

Les quatre routes relaient le fournisseur. La réponse a toujours la même forme : {"data": {"status", "message", "result"}}, où result est la charge utile du fournisseur.

GET /services/{code}/backups

Permissions : services.backups:read

Répond même sur un service suspendu.

{ "data": { "status": "SUCCESS", "message": "OK", "result": {
  "customerEnabled": true,
  "limits": { "max": 6, "used": 2 },
  "customer": [
    { "id": "9b5d3938-cbd9-4946-8357-05badcdf6c33",
      "note": null, "status": "COMPLETED",
      "createdAt": "2026-08-15T19:50:45.282411", "sizeBytes": 21474837581 }
  ],
  "internal": []
} } }

Le id d'une sauvegarde est une chaîne, propre au fournisseur. C'est ce que prennent la suppression et la restauration.

POST /services/{code}/backups

Permissions : services.backups:write

{ "data": { "status": "PENDING", "message": "VPS backup in progress",
  "result": { "taskId": "d3b780a2-308f-40bf-95a2-0316d8872721", "status": "PENDING" } } }

DELETE /services/{code}/backups/{backupId}

Permissions : services.backups:write

backupId vient de result.customer[].id. Un identifiant inconnu répond 400 BACKUP_NOT_FOUND.

POST /services/{code}/backups/restore

Permissions : services.backups:write

Écrase le disque.

Mêmes refus que la création, plus 400 MISSING_FIELDS quand source est absent ou que l'identifiant qui va avec manque.

POST /services/{code}/reinstall

Permissions : services.reinstall:write Débit : 2 par minute, par clé et par service. Les appels refusés comptent.

Détruit le disque. Sur un serveur de jeu, remet le serveur à zéro et le corps peut être vide.

authValue est stocké chiffré, n'est jamais renvoyé, et cet appel n'est jamais journalisé avec son corps.

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -d '{"os":"debian-13","authType":"SSH_KEY","authValue":"ssh-ed25519 AAAAC3Nza... admin@laptop"}' \
     https://api.freshperf.fr/v1/services/SRV-TIYMZT-8349/reinstall

{ "data": { "status": "PENDING", "message": "reinstalling" } }

GET /services/{code}/addons

Permissions : services.addons:read

{ "data": {
  "addons": [
    { "shortname": "extra-saves", "title": "Sauvegardes supplémentaires",
      "kind": "BACKUP_SLOTS", "status": "ACTIVE", "quantity": 1,
      "unitPriceCents": 399, "unitTaxCents": 80,
      "linePriceCents": 399, "lineTaxCents": 80,
      "nextCycleLinePriceCents": 399, "nextCycleLineTaxCents": 80,
      "pendingRemovalQuantity": 0 }
  ],
  "available": [
    { "shortname": "extra-ram-1gb", "title": { "fr-fr": "+1 Go RAM", "en-us": "+1 Gb RAM" },
      "kind": "RESOURCE_DELTA", "resourceKey": "ramSize", "unitDelta": 1024,
      "unitPriceCents": 200, "maxQuantity": 10 }
  ],
  "recurringTotalCents": 479
} }

Ajouter ou retirer une option se fait dans le tableau de bord.

PATCH /services/{code}

Permissions : services:write

curl -X PATCH -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" -d '{"customName":"prod-eu-1"}' \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951

Répond le service complet, comme GET /services/{code}.

POST /services/{code}/renew

Permissions : services:write et billing.invoices:pay, plus billing.saved_methods:charge dès que le financement touche une carte. En-tête obligatoire : Idempotency-Key.

Débite le cycle suivant tout de suite et avance la date de facturation.

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: renew-SRV-TJUAQ1-1951-2026-08" \
     -d '{"method":"balance"}' \
     https://api.freshperf.fr/v1/services/SRV-TJUAQ1-1951/renew

{ "data": { "status": "CHARGED", "serviceCode": "SRV-TJUAQ1-1951",
            "nextBillingAt": 1793091315189, "amountCents": 360 } }

status ne vaut que CHARGED : toute autre issue est une erreur. amountCents est le montant débité, taxe comprise.

POST /services/{code}/actions/{action}

Permissions : elles dépendent de l'action envoyée.

La passerelle brute vers le fournisseur. Elle sert au pare-feu et au DNS inverse, qui n'ont pas de route dédiée.

Aucune autre action n'est joignable. Il n'existe pas de firewall_add, firewall_set ni firewall_remove : une règle se crée, se modifie et se supprime avec firewall_create, firewall_update et firewall_delete.

Les actions de panneau de jeu (files, databases, allocations, schedules, startup, versions, content, subdomains, sftp, subusers) répondent 403 API_ACTION_NOT_ALLOWED quelles que soient les permissions de la clé.

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -d '{"arguments":{"op":"set","address":"203.0.113.224","hostname":"vps.exemple.fr"}}' \
     https://api.freshperf.fr/v1/services/SRV-TIYMZT-8349/actions/rdns

{ "data": { "status": "SUCCESS", "message": "Action completed", "result": {
  "configured": true,
  "entries": [
    { "family": "ipv4", "address": "203.0.113.224", "hostname": "vps.exemple.fr", "zoneConfigured": true }
  ]
} } }

rdns prend op valant get, set ou delete, plus address (une adresse rendue par /status) et, pour set, hostname. Les arguments des actions firewall_* dépendent de l'hyperviseur : lisez firewall_list pour voir la forme d'une règle avant d'en écrire une.

Préférez les routes typées (/power, /backups, /reinstall, /console/command) partout où elles existent : elles sont stables et indépendantes du fournisseur.