Serveurs de jeu
Les routes de cette page pilotent un serveur de jeu. Elles vivent sous /v1/services/{code}/games et prennent toutes le code du service (SRV-TM8K2P-3317), donné par GET /services. Un service d'un autre type (VPS, hébergement web) répond 409 SERVICE_TYPE_NOT_SUPPORTED.
Les autres identifiants viennent des routes de liste : jobId d'une tâche d'archive, databaseId de GET .../games/databases, scheduleId de GET .../games/schedules (un entier), installId d'une installation. Ils sont opaques : ne les construisez pas.
Conventions de ces routes
Les règles générales de Requêtes et réponses s'appliquent. Ce qui change ici :
| Sujet | Règle |
|---|---|
| Enveloppe | {"data": ...}. data porte les champs que chaque route liste ci-dessous |
| Listes | sous la clé que chaque route nomme (entries, rows, results, items...). Aucune pagination, sauf page et limit sur les recherches de catalogue |
| Champs des réponses | les réponses de cette page listent les champs garantis. Une réponse peut en porter d'autres : ignorez ceux que vous ne connaissez pas |
| Champ obligatoire absent ou vide | 400 VALIDATION_ERROR:<champ>, avant tout appel au serveur |
| Refus du serveur | 409 avec un code en majuscules (FILES_BUSY, SERVER_NOT_STOPPED, SCHEDULE_LIMIT_REACHED...). Un code en _BUSY porte Retry-After: 5. Une valeur refusée sans code (un chemin avec ..) répond 502 ACTION_FAILED |
| Service suspendu ou qui n'est plus actif | 409 SERVICE_NOT_ACTIVE sur toutes les routes, lectures comprises, sauf GET .../games/features et GET .../games/sftp |
| Serveur pas encore créé | 409 INSTANCE_NOT_PROVISIONED |
| Budget d'actions | chaque appel dépense le budget d'actions du compte, partagé avec le tableau de bord (Limites de débit et idempotence). Au-delà : 429 API_RATE_LIMITED avec Retry-After |
| Selon le jeu | GET .../games/features dit ce que le serveur propose. Les mondes et les paramètres du jeu sont réservés à Minecraft : 409 WORLD_NOT_SUPPORTED, 409 SETTINGS_NOT_SUPPORTED ailleurs |
| Dates | chaînes ISO 8601 avec leur décalage, sauf current.installedAt de GET .../games/versions et startedAt / updatedAt des installations de contenu, sans décalage, et info.lastPlayed des mondes, entier en millisecondes epoch |
Statuts de succès
| Statut | Quand |
|---|---|
200 | l'opération est faite, ou c'est une lecture |
201 | création faite : POST .../files/directories, POST .../databases, POST .../schedules |
202 | opération longue lancée. Le tableau ci-dessous dit quoi relire |
Route qui répond 202 | Relisez | Jusqu'à |
|---|---|---|
POST .../files/compress, .../files/decompress, .../world/export | GET .../files/jobs/{jobId} → job.status | completed, failed ou detached |
POST .../world/import/extract | GET .../world → staging.extraction | completed ou failed |
POST .../world/import/fetch | GET .../world → staging.archives | l'archive est listée |
POST .../versions/installs | GET .../versions/installs/{installId} → status | completed ou failed |
POST .../content/installs | GET .../content/installs/{installId} → status | completed, failed ou cancelled |
POST .../schedules/{scheduleId}/run | GET .../schedules → rows[].isProcessing | false |
Relisez toutes les 2 à 5 secondes.
Idempotence
4 routes exigent l'en-tête Idempotency-Key :
| Route | Effet |
|---|---|
POST /services/{code}/games/databases | create |
POST /services/{code}/games/databases/{databaseId}/password | rotate-password |
POST /services/{code}/games/versions/installs | install |
POST /services/{code}/games/content/installs | install |
Mots de passe rendus une fois
POST .../databases et POST .../databases/{databaseId}/password répondent le mot de passe de la base, une seule fois. GET .../databases ne le rend jamais, et un rejeu de la même Idempotency-Key répond la base sans lui, avec credentialsRedacted: true. Le mot de passe SFTP est celui de votre compte FreshPerf : aucune route ne le rend.
Permissions
| Permission | Routes |
|---|---|
services:read | GET .../games/features |
games.sftp:read | GET .../games/sftp |
games.files:read | GET .../games/files, GET .../games/files/content, GET .../games/files/jobs, GET .../games/files/jobs/{jobId}, GET .../games/world, GET .../games/world/catalog, GET .../games/world/catalog/{projectId}/files |
games.files:write | PUT .../games/files/content, POST .../games/files/rename, POST .../games/files/copy, POST .../games/files/delete, POST .../games/files/directories, POST .../games/files/chmod, POST .../games/files/compress, POST .../games/files/decompress, POST .../games/world/export, POST .../games/world/reset, POST .../games/world/activate, POST .../games/world/rename, POST .../games/world/delete, POST .../games/world/import/fetch, POST .../games/world/import/stage, POST .../games/world/import/extract, POST .../games/world/import/apply, DELETE .../games/world/import |
games.databases:read | GET .../games/databases |
games.databases:write | POST .../games/databases, POST .../games/databases/{databaseId}/password, DELETE .../games/databases/{databaseId} |
games.schedules:read | GET .../games/schedules |
games.schedules:write | POST .../games/schedules, PUT .../games/schedules/{scheduleId}, POST .../games/schedules/{scheduleId}/toggle, POST .../games/schedules/{scheduleId}/run, DELETE .../games/schedules/{scheduleId} |
games.startup:read | GET .../games/startup |
games.startup:write | PUT .../games/startup/variables/{key}, PUT .../games/startup/image |
games.versions:read | GET .../games/versions, GET .../games/versions/types, GET .../games/versions/types/{type}/versions, GET .../games/versions/types/{type}/versions/{version}/builds, GET .../games/versions/installs/{installId} |
games.versions:write | POST .../games/versions/installs |
games.content:read | GET .../games/content/providers, GET .../games/content/context, GET .../games/content/search, GET .../games/content/projects/{provider}/{projectId}, GET .../games/content/projects/{provider}/{projectId}/versions, GET .../games/content/projects/{provider}/{projectId}/update, GET .../games/content/installs, GET .../games/content/installs/{installId}, GET .../games/content/installed |
games.content:write | POST .../games/content/installs, POST .../games/content/installs/{installId}/cancel, POST .../games/content/installed/remove, POST .../games/content/installed/toggle |
games.settings:read | GET .../games/settings |
games.settings:write | PATCH .../games/settings |
services.console:write | POST .../games/schedules/{scheduleId}/run |
services.power:write | POST .../games/schedules/{scheduleId}/run |
Un :write donne le :read du même nom. Deux permissions s'ajoutent selon ce que la requête contient :
| Requête | Demande en plus |
|---|---|
une tâche planifiée avec une étape command (création, modification) | services.console:write |
une tâche planifiée avec une étape restart ou stop | services.power:write |
armer une tâche (POST .../toggle avec isActive: true) ou la lancer | services.console:write et services.power:write |
online-mode dans values de PATCH .../settings | services.console:write |
Sans elle : 403 API_SCOPE_MISSING:<permission>. Sur un compte partagé avec vous, l'accès doit vous accorder sur le service la permission correspondante (fichiers, SFTP, bases de données, tâches planifiées, démarrage, versions, contenu, paramètres du jeu), plus la console et l'alimentation dans les cas ci-dessus.
Hors de l'API
Restent au tableau de bord : l'envoi et le téléchargement de fichiers (utilisez SFTP), le téléchargement d'un fichier depuis une adresse web, les joueurs, les ports et les sous-domaines. La console, l'alimentation et la réinstallation sont dans Gérer vos services.
Fonctions du serveur
GET /services/{code}/games/features
Permissions : services:read
Ce que ce serveur de jeu propose en plus des fichiers, bases de données, tâches planifiées et paramètres de démarrage, selon son jeu : sftp, versions, content, world, game-settings (les routes de paramètres du jeu). La liste peut aussi contenir players et subdomains, qui restent au tableau de bord. gameType vaut minecraft sur un serveur Minecraft. Répond aussi sur un service suspendu.
Réponse 200 : {data: {features: [{id, label}], gameType}}
GET /services/{code}/games/sftp
Permissions : games.sftp:read
Le nom d'utilisateur, l'hôte et le port de connexion. Le mot de passe est celui du compte FreshPerf du titulaire de la clé, jamais rendu. Répond aussi sur un service suspendu.
state | Sens |
|---|---|
SYNCED | connectez-vous avec le mot de passe du compte |
UNSYNCED | le mot de passe du compte n'est pas encore actif sur SFTP : reconnectez-vous au tableau de bord ou changez votre mot de passe |
NOT_PROVISIONED | l'accès du titulaire d'un compte partagé est en cours de création. La réponse ne porte que state : relisez dans un instant |
Réponse 200 : {data: {username, host, port, state}}
Fichiers
Exemple :
curl -s https://api.freshperf.fr/v1/services/SRV-TM8K2P-3317/games/files?directory=/plugins \ -H "Authorization: Bearer $FRESHPERF_KEY"
{"data": {"entries": [{"name": "config.yml", "mode": "-rw-r--r--", "modeBits": "644", "size": 1824, "isFile": true, "isSymlink": false, "mimetype": "text/plain", "modifiedAt": "2026-10-30T18:04:11+00:00"}]}}
GET /services/{code}/games/files
Permissions : games.files:read
Le contenu du dossier. 409 FILES_BUSY quand trop d'opérations de fichiers lentes (lister, copier, supprimer) tournent déjà : réessayez.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
directory | requête | string | non | Dossier, / par défaut |
Réponse 200 : {data: {entries: [{name, mode, modeBits, size, isFile, isSymlink, mimetype, modifiedAt}]}}
GET /services/{code}/games/files/content
Permissions : games.files:read
Le contenu d'un fichier texte. Un fichier binaire ne passe pas intact : lisez archives et jars par SFTP.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
file | requête | string | oui | Chemin depuis la racine du serveur |
Réponse 200 : {data: {content}}
PUT /services/{code}/games/files/content
Permissions : games.files:write
Crée le fichier ou remplace son contenu.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
file | corps | string | oui | Chemin depuis la racine du serveur, par exemple /plugins/config.yml |
content | corps | string | non | Le nouveau contenu (texte) ; vide s'il est absent |
Réponse 200 : {data: {status}}
POST /services/{code}/games/files/rename
Permissions : games.files:write
Chaque paire est relative à root ; un to dans un autre dossier déplace le fichier.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier auquel les chemins sont relatifs, / par défaut |
files | corps | tableau de RenamePair | oui |
Chaque élément RenamePair :
| Champ | Type | Requis | Valeurs et format |
|---|---|---|---|
from | string | oui | |
to | string | oui |
Réponse 200 : {data: {renamed}}
POST /services/{code}/games/files/copy
Permissions : games.files:write
La copie est créée à côté du fichier. 409 FILES_BUSY comme pour la liste.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
location | corps | string | oui | Chemin du fichier à copier |
Réponse 200 : {data: {status}}
POST /services/{code}/games/files/delete
Permissions : games.files:write
Supprime fichiers et dossiers avec leur contenu, définitivement. 409 FILES_BUSY comme pour la liste.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier auquel les noms sont relatifs, / par défaut |
files | corps | string[] | oui | Noms ou chemins dans root |
Réponse 200 : {data: {deleted}}
POST /services/{code}/games/files/directories
Permissions : games.files:write
Les dossiers intermédiaires sont créés au besoin.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier parent, / par défaut |
name | corps | string | oui | Nom ; / permis pour des dossiers imbriqués |
Réponse 201 : {data: {status}}
POST /services/{code}/games/files/chmod
Permissions : games.files:write
Modes octaux, par exemple 644.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier auquel les noms sont relatifs, / par défaut |
files | corps | tableau de ChmodEntry | oui |
Chaque élément ChmodEntry :
| Champ | Type | Requis | Valeurs et format |
|---|---|---|---|
file | string | oui | Nom dans root |
mode | string | oui | Mode octal, par exemple 644 |
Réponse 200 : {data: {chmoded}}
POST /services/{code}/games/files/compress
Permissions : games.files:write
Lance une archive .tar.gz des fichiers de root et répond 202 avec la tâche : relisez GET .../files/jobs/{jobId}. Une seule tâche d'archive à la fois par serveur (409 ARCHIVE_ALREADY_RUNNING) ; ARCHIVE_NAME_TAKEN, ARCHIVE_NAME_INVALID pour un nom refusé.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier auquel les noms sont relatifs, / par défaut |
files | corps | string[] | oui | Noms dans root |
name | corps | string | non | Nom de l'archive ; .tar.gz est ajouté s'il manque. Un nom généré s'il est absent |
Réponse 202 : {data: {job: {jobId, kind, status, root, entryCount, requestedName, name, sizeBytes, error}}} ; kind vaut compress ou extract
POST /services/{code}/games/files/decompress
Permissions : games.files:write
Lance l'extraction de l'archive dans son dossier et répond 202 avec la tâche : relisez GET .../files/jobs/{jobId}. Elle partage avec l'archivage la tâche unique par serveur (409 ARCHIVE_ALREADY_RUNNING).
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
root | corps | string | non | Dossier de l'archive, / par défaut |
file | corps | string | oui | Nom de l'archive dans root (un seul nom, sans /) |
Réponse 202 : {data: {job: {...}}}
GET /services/{code}/games/files/jobs
Permissions : games.files:read
La tâche d'archive ou d'extraction en cours sur le serveur, ou null.
Réponse 200 : {data: {job}}
GET /services/{code}/games/files/jobs/{jobId}
Permissions : games.files:read
status : queued, running, completed, failed ou detached. detached ne change plus : l'opération se poursuit sur le serveur sans suivi : une compression y dépose son archive sous un nom généré au lieu de celui demandé, une extraction continue d'écrire ses fichiers. Relisez le dossier (GET .../files) pour voir le résultat.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
jobId | chemin | string | oui | jobId de la tâche |
Réponse 200 : {data: {job: {...}}}
Mondes (Minecraft)
GET /services/{code}/games/world
Permissions : games.files:read
Serveurs Minecraft (409 WORLD_NOT_SUPPORTED sinon) : les mondes, le monde actif (levelName), les archives à la racine du serveur, la zone d'import et la tâche en cours.
reason (avec supported: false) | Cas |
|---|---|
NOT_JAVA | une édition autre que Java |
PROXY | un proxy |
WORLD_CONTAINER | les mondes sont rangés dans un autre dossier, nommé par container |
Avec NOT_JAVA ou PROXY, les autres routes de mondes, hors GET .../world et les deux routes GET .../world/catalog, répondent 409 WORLD_NOT_SUPPORTED ; avec WORLD_CONTAINER, celles qui exportent, régénèrent, activent, renomment, suppriment ou appliquent un monde (import/apply). staging.extraction vaut none, running, completed, failed ou unsettled (l'extraction se poursuit sans suivi : relisez).
Réponse 200 : {data: {supported, levelName, worlds: [...], archives: [...], staging, job, busy, ...}}
POST /services/{code}/games/world/export
Permissions : games.files:write
Lance une archive du monde à la racine du serveur et répond 202 avec la tâche (relisez GET .../files/jobs/{jobId}). Sur un serveur démarré, le monde est d'abord sauvegardé (save-all flush). 409 SERVER_TRANSITIONING pendant un démarrage ou un arrêt.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
world | corps | string | non | Nom du dossier du monde ; le monde actif s'il est absent |
Réponse 202 : {data: {job, archive, running, saved}}
POST /services/{code}/games/world/reset
Permissions : games.files:write
Remplace le monde actif par un nouveau. Le serveur doit être arrêté (409 SERVER_NOT_STOPPED). L'ancien monde est gardé dans un dossier de sauvegarde, sauf avec keepBackup: false.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
seed | corps | string | non | Graine (64 caractères au plus) ; aléatoire si absente ou vide |
levelType | corps | string | non | Type de monde ; valeurs : normal, flat, large_biomes, amplified |
keepBackup | corps | boolean | non | Garder le monde actuel dans un dossier de sauvegarde, true par défaut. false le supprime |
Réponse 200 : {data: {backup, confirmed}}
POST /services/{code}/games/world/activate
Permissions : games.files:write
Fait démarrer le serveur sur un autre dossier de monde. Le serveur doit être arrêté.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
world | corps | string | oui | Nom du dossier du monde |
Réponse 200 : {data: {backup, confirmed}}
POST /services/{code}/games/world/rename
Permissions : games.files:write
Pas le monde actif (409 WORLD_IS_ACTIVE). Le serveur doit être arrêté.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
world | corps | string | oui | Nom actuel du dossier |
name | corps | string | oui | Nouveau nom du dossier |
Réponse 200 : {data: {backup, confirmed}}
POST /services/{code}/games/world/delete
Permissions : games.files:write
Pas le monde actif. Supprimé définitivement. Le serveur doit être arrêté.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
world | corps | string | oui | Nom du dossier du monde |
Réponse 200 : {data: {backup, confirmed}}
GET /services/{code}/games/world/catalog
Permissions : games.files:read
Cartes à télécharger (409 WORLD_CATALOG_UNAVAILABLE quand le catalogue est désactivé).
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
query | requête | string | non | Termes recherchés |
page | requête | integer | non | Page, à partir de 0 |
limit | requête | integer | non | 1 à 50, 20 par défaut |
Réponse 200 : {data: {results: [{provider, projectId, name, author, description, iconUrl, downloads, type}]}}
GET /services/{code}/games/world/catalog/{projectId}/files
Permissions : games.files:read
Les versions téléchargeables d'un monde du catalogue.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
projectId | chemin | string | oui | projectId de la recherche |
Réponse 200 : {data: {versions: [{versionId, name, gameVersions, fileName, fileSize, available, ...}]}}
POST /services/{code}/games/world/import/fetch
Permissions : games.files:write
Le serveur télécharge le fichier dans la zone d'import et répond 202 ; GET /games/world le montre dans staging une fois arrivé. Extrayez-le ensuite.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
projectId | corps | string | oui | projectId de GET /games/world/catalog |
fileId | corps | string | oui | versionId de GET /games/world/catalog/{projectId}/files |
Réponse 202 : {data: {status, file, expectedSize}}
POST /services/{code}/games/world/import/stage
Permissions : games.files:write
Déplace une archive de la racine du serveur (un export, une archive que vous avez faite) dans la zone d'import.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
file | corps | string | oui | Nom de l'archive |
Réponse 200 : {data: {file}}
POST /services/{code}/games/world/import/extract
Permissions : games.files:write
Répond 202 avec la tâche d'extraction ; GET /games/world liste ensuite les mondes trouvés (staging.candidates).
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
file | corps | string | oui | Nom de l'archive |
Réponse 202 : {data: {job}}
POST /services/{code}/games/world/import/apply
Permissions : games.files:write
Remplace le monde actif par le monde importé. Le serveur doit être arrêté. Le monde remplacé est gardé dans un dossier de sauvegarde, sauf avec keepBackup: false.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
candidate | corps | string | non | staging.candidates[].path de GET /games/world ; vide quand le dossier extrait est lui-même le monde |
keepBackup | corps | boolean | non | Garder le monde remplacé dans un dossier de sauvegarde, true par défaut |
Réponse 200 : {data: {backup, confirmed}}
DELETE /services/{code}/games/world/import
Permissions : games.files:write
Vide la zone d'import ; une archive placée là retourne à la racine du serveur.
Réponse 200 : {data: {}}
Bases de données
Exemple :
curl -s -X POST https://api.freshperf.fr/v1/services/SRV-TM8K2P-3317/games/databases \ -H "Authorization: Bearer $FRESHPERF_KEY" -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" -d '{"name": "shop"}'
{"data": {"database": {"id": "x3Vq9k", "name": "s12_shop", "host": "db1.freshperf.fr", "port": 3306, "username": "u12_Ab3dEf", "connectionsFrom": "%", "maxConnections": 0, "password": "q8Zr...Lw"}}}
GET /services/{code}/games/databases
Permissions : games.databases:read
Informations de connexion sans les mots de passe : un mot de passe n'est montré qu'une fois, à la création de la base ou à sa réinitialisation. limit est le quota de l'offre, null quand elle n'en fixe pas.
Réponse 200 : {data: {rows: [{id, name, host, port, username, connectionsFrom, maxConnections}], limit}} ; maxConnections vaut null ou 0 sans limite
POST /services/{code}/games/databases
Permissions : games.databases:write · En-tête : Idempotency-Key
Répond la base avec son mot de passe, une fois : un rejeu de la même Idempotency-Key la répond sans (credentialsRedacted). 409 DATABASE_QUOTA_REACHED, DATABASE_INVALID_NAME, DATABASE_INVALID_REMOTE.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
name | corps | string | oui | 3 à 32 lettres, chiffres, _ ou - |
remote | corps | string | non | Hôtes autorisés à se connecter, % (tous) par défaut |
Réponse 201 : {data: {database: {id, name, host, port, username, connectionsFrom, maxConnections, password}}}
POST /services/{code}/games/databases/{databaseId}/password
Permissions : games.databases:write · En-tête : Idempotency-Key
Un nouveau mot de passe, rendu une fois ; l'ancien cesse de fonctionner. 10 par minute au plus par compte, 429 API_RATE_LIMITED au-delà.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
databaseId | chemin | string | oui | id de la base |
Réponse 200 : {data: {database: {..., password}}}
DELETE /services/{code}/games/databases/{databaseId}
Permissions : games.databases:write
Avec ses données, définitivement.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
databaseId | chemin | string | oui | id de la base |
Réponse 200 : {data: {status}}
Tâches planifiées
Exemple :
curl -s -X POST https://api.freshperf.fr/v1/services/SRV-TM8K2P-3317/games/schedules \ -H "Authorization: Bearer $FRESHPERF_KEY" -H "Content-Type: application/json" \ -d '{"name": "Redémarrage nocturne", "minute": "0", "hour": "4", "steps": [{"kind": "command", "command": "say Redémarrage dans 60 s"}, {"kind": "restart", "offsetSeconds": 60}]}'
{"data": {"status": "created"}}
GET /services/{code}/games/schedules
Permissions : games.schedules:read
Avec les limites (limits : 10 tâches, 10 étapes, 900 secondes de décalage) et le fuseau horaire (timezone) dans lequel les champs cron sont lus.
| Champ | Sens quand il vaut false |
|---|---|
editable | la tâche contient ce que cette API n'écrit pas (une autre sorte d'étape, une valeur hors bornes) |
armable | la tâche peut être mise en pause ou supprimée, mais ni armée ni lancée (409 SCHEDULE_READ_ONLY) tant qu'un PUT ne l'a pas réenregistrée |
Réponse 200 : {data: {rows: [{id, name, minute, hour, dayOfMonth, month, dayOfWeek, isActive, isProcessing, lastRunAt, nextRunAt, steps, editable, armable}], limits: {schedules, steps, offsetSeconds}, timezone}}
POST /services/{code}/games/schedules
Permissions : games.schedules:write
Une étape command demande aussi services.console:write, une étape restart ou stop services.power:write. Une tâche ne se déclenche que si le serveur est démarré. 409 SCHEDULE_LIMIT_REACHED, SCHEDULE_TOO_MANY_STEPS, SCHEDULE_INVALID_*, SCHEDULE_REJECTED.
Champs cron : * s'ils sont absents ou vides. Chacun accepte *, une valeur, une plage (1-5), une liste (1,15) et un pas sur * ou sur une plage (*/15).
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
name | corps | string | oui | 1 à 60 caractères |
minute | corps | string | non | 0-59 |
hour | corps | string | non | 0-23 |
dayOfMonth | corps | string | non | 1-31 |
month | corps | string | non | 1-12 |
dayOfWeek | corps | string | non | 0-7, 0 et 7 étant dimanche |
isActive | corps | boolean | non | Armée, true par défaut |
steps | corps | tableau de ScheduleStep | oui | 1 à 10 étapes |
Chaque élément ScheduleStep :
| Champ | Type | Requis | Valeurs et format |
|---|---|---|---|
kind | string | oui | valeurs : command, restart, stop |
command | string | non | Commande console (500 caractères au plus), pour command |
offsetSeconds | integer | non | Secondes après l'étape précédente, 0 à 900, 0 par défaut |
Réponse 201 : {data: {status: "created"}}
PUT /services/{code}/games/schedules/{scheduleId}
Permissions : games.schedules:write
Remplace la tâche : envoyez tous les champs. Mêmes permissions supplémentaires, règles et refus qu'à la création, sauf SCHEDULE_LIMIT_REACHED. 409 SCHEDULE_BUSY pendant qu'elle s'exécute, SCHEDULE_NOT_FOUND pour un scheduleId inconnu.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
scheduleId | chemin | integer | oui | id de la tâche |
name | corps | string | oui | 1 à 60 caractères |
minute | corps | string | non | 0-59 |
hour | corps | string | non | 0-23 |
dayOfMonth | corps | string | non | 1-31 |
month | corps | string | non | 1-12 |
dayOfWeek | corps | string | non | 0-7, 0 et 7 étant dimanche |
isActive | corps | boolean | non | Armée, true par défaut |
steps | corps | tableau de ScheduleStep | oui | 1 à 10 étapes |
Chaque élément ScheduleStep :
| Champ | Type | Requis | Valeurs et format |
|---|---|---|---|
kind | string | oui | valeurs : command, restart, stop |
command | string | non | Commande console (500 caractères au plus), pour command |
offsetSeconds | integer | non | Secondes après l'étape précédente, 0 à 900, 0 par défaut |
Réponse 200 : {data: {status: "updated"}}
POST /services/{code}/games/schedules/{scheduleId}/toggle
Permissions : games.schedules:write
Armer une tâche, c'est la déclencher à sa prochaine échéance : cela demande aussi services.console:write et services.power:write. La mettre en pause ne demande rien de plus. 409 SCHEDULE_READ_ONLY pour armer une tâche armable: false.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
scheduleId | chemin | integer | oui | id de la tâche |
isActive | corps | boolean | oui |
Réponse 200 : {data: {status: "active"|"paused"}}
POST /services/{code}/games/schedules/{scheduleId}/run
Permissions : games.schedules:write, services.console:write, services.power:write
Exécute maintenant ses commandes et ses étapes d'alimentation. 409 SCHEDULE_INACTIVE sur une tâche en pause, SCHEDULE_BUSY pendant qu'elle s'exécute, SCHEDULE_READ_ONLY sur une tâche armable: false, INSTALL_IN_PROGRESS pendant une installation.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
scheduleId | chemin | integer | oui | id de la tâche |
Réponse 202 : {data: {status: "queued"}}
DELETE /services/{code}/games/schedules/{scheduleId}
Permissions : games.schedules:write
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
scheduleId | chemin | integer | oui | id de la tâche |
Réponse 200 : {data: {status: "deleted"}}
Démarrage
GET /services/{code}/games/startup
Permissions : games.startup:read
Les variables que ce serveur vous laisse modifier (widget : text, select, number, boolean) et, quand le jeu propose un choix, l'image d'exécution ; runtime vaut null sinon. label et description sont des objets indexés par langue (fr-fr, en-us).
Réponse 200 : {data: {fields: [{env, value, rules, label, description, widget, options, ...}], runtime: {current, options, ...}}}
PUT /services/{code}/games/startup/variables/{key}
Permissions : games.startup:write
S'applique au prochain démarrage. 409 VARIABLE_REJECTED pour une variable non proposée ou une valeur refusée, INSTALL_IN_PROGRESS pendant une installation.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
key | chemin | string | oui | env de la variable |
value | corps | string | non | Pour une variable à liste, une de ses options ; vide si absent |
Réponse 200 : {data: {value}}
PUT /services/{code}/games/startup/image
Permissions : games.startup:write
Une des runtime.options ; s'applique au prochain démarrage, rien n'est réinstallé. 409 INVALID_DOCKER_IMAGE pour une valeur hors de runtime.options, INSTALL_IN_PROGRESS pendant une installation.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
image | corps | string | oui |
Réponse 200 : {data: {image}}
Logiciel serveur
Exemple :
curl -s -X POST https://api.freshperf.fr/v1/services/SRV-TM8K2P-3317/games/versions/installs \ -H "Authorization: Bearer $FRESHPERF_KEY" -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" -d '{"type": "PAPER", "version": "1.21.4"}'
{"data": {"installId": "c2f6a1d0-5b7e-4f3a-9d21-0e8b7c4a6f15"}}
GET /services/{code}/games/versions
Permissions : games.versions:read
Ce que FreshPerf a installé en dernier (current) et l'installation en cours (active). Chacun vaut null quand il n'y a rien.
Réponse 200 : {data: {active, current: {type, versionId, build, java, installedAt}}}
GET /services/{code}/games/versions/types
Permissions : games.versions:read
Vanilla, Paper, Fabric, Forge...
Réponse 200 : {data: {types: [{id, name, category, description, deprecated, experimental, ...}]}}
GET /services/{code}/games/versions/types/{type}/versions
Permissions : games.versions:read
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
type | chemin | string | oui | id du logiciel |
Réponse 200 : {data: {versions: [{versionId, releaseType, java, supported, builds, latestBuildId, latestBuildName}]}}
GET /services/{code}/games/versions/types/{type}/versions/{version}/builds
Permissions : games.versions:read
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
type | chemin | string | oui | id du logiciel |
version | chemin | string | oui | versionId |
Réponse 200 : {data: {builds: [{id, name, buildNumber, created, experimental}]}}
POST /services/{code}/games/versions/installs
Permissions : games.versions:write · En-tête : Idempotency-Key
Arrête le serveur, installe le logiciel, passe l'exécution sur sa version de Java et redémarre le serveur. Répond 202 avec installId : relisez GET .../versions/installs/{installId}. 409 INSTALL_IN_PROGRESS et les autres *_IN_PROGRESS pendant qu'autre chose tourne, SCHEDULE_RUNNING pendant qu'une tâche planifiée s'exécute.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
type | corps | string | oui | id de GET /games/versions/types, par exemple PAPER |
version | corps | string | oui | versionId de GET /games/versions/types/{type}/versions |
buildId | corps | string | non | id de la liste des builds ; le dernier build s'il est absent |
Réponse 202 : {data: {installId}}
GET /services/{code}/games/versions/installs/{installId}
Permissions : games.versions:read
status : queued, running, completed, failed ; step et progress (0-100) pendant l'installation. step : QUEUED, STOPPING, CLEANING, DOWNLOADING, INSTALLING, UPDATING_RUNTIME, CONFIGURING, STARTING, DONE, ERROR. error n'est présent qu'après un échec.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
installId | chemin | string | oui | installId de l'installation |
Réponse 200 : {data: {installId, status, step, progress, type, versionId, build, error}}
Mods, plugins et modpacks
GET /services/{code}/games/content/providers
Permissions : games.content:read
Modrinth, CurseForge, Hangar, Spigot selon ce qui est activé, avec les types que chacun propose.
Réponse 200 : {data: {providers: [{id, name, supportedTypes}]}}
GET /services/{code}/games/content/context
Permissions : games.content:read
D'après la dernière version installée par FreshPerf : les critères sur lesquels filtrer la recherche.
Réponse 200 : {data: {hasContext, gameVersion, loader, software}}
GET /services/{code}/games/content/search
Permissions : games.content:read
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
type | requête | string | non | mod (par défaut), plugin ou modpack |
query | requête | string | non | Termes recherchés |
provider | requête | string | non | Cette source seulement |
gameVersion | requête | string | non | Version du jeu, par exemple 1.21.4 |
loader | requête | string | non | Loader, par exemple fabric |
page | requête | integer | non | Page, à partir de 0 |
limit | requête | integer | non | 1 à 50, 20 par défaut |
Réponse 200 : {data: {results: [{provider, projectId, name, author, description, iconUrl, downloads, type}]}}
GET /services/{code}/games/content/projects/{provider}/{projectId}
Permissions : games.content:read
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
provider | chemin | string | oui | provider de la recherche |
projectId | chemin | string | oui | projectId de la recherche |
Réponse 200 : {data: {project: {provider, projectId, name, author, description, gameVersions, loaders, ...}}}
GET /services/{code}/games/content/projects/{provider}/{projectId}/versions
Permissions : games.content:read
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
provider | chemin | string | oui | provider de la recherche |
projectId | chemin | string | oui | projectId de la recherche |
gameVersion | requête | string | non | Seulement les versions pour cette version du jeu |
loader | requête | string | non | Seulement les versions pour ce loader |
Réponse 200 : {data: {versions: [{versionId, name, gameVersions, loaders, fileName, fileSize, releaseType, datePublished}]}}
GET /services/{code}/games/content/projects/{provider}/{projectId}/update
Permissions : games.content:read
Si une version plus récente que versionId correspond à la version du jeu et au loader.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
provider | chemin | string | oui | provider de la recherche |
projectId | chemin | string | oui | projectId de la recherche |
versionId | requête | string | non | La version installée |
gameVersion | requête | string | non | |
loader | requête | string | non | |
type | requête | string | non | mod, plugin ou modpack |
Réponse 200 : {data: {updateAvailable, latest}}
GET /services/{code}/games/content/installs
Permissions : games.content:read
L'installation en cours, ou null ; avec withLatestModpack=true, aussi la dernière installation de modpack.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
withLatestModpack | requête | boolean | non | Rendre aussi la dernière installation de modpack |
Réponse 200 : {data: {active, latestModpack}}
POST /services/{code}/games/content/installs
Permissions : games.content:write · En-tête : Idempotency-Key
Répond 202 avec installId : relisez GET .../content/installs/{installId}. Un modpack arrête et redémarre le serveur ; deleteWorld supprime le monde actuel définitivement. 409 INSTALL_IN_PROGRESS et les autres *_IN_PROGRESS pendant qu'autre chose tourne ; pour un modpack, SCHEDULE_RUNNING pendant qu'une tâche planifiée s'exécute.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
provider | corps | string | oui | provider des résultats de recherche |
projectId | corps | string | oui | projectId des résultats de recherche |
versionId | corps | string | oui | versionId de GET .../projects/{provider}/{projectId}/versions |
type | corps | string | non | mod par défaut ; valeurs : mod, plugin, modpack |
projectName | corps | string | non | Nom affiché gardé avec le fichier installé |
versionName | corps | string | non | Nom affiché de la version |
gameVersion | corps | string | non | |
loader | corps | string | non | |
clean | corps | boolean | non | Modpacks : retirer d'abord le contenu du pack précédent |
deleteWorld | corps | boolean | non | Modpacks : supprimer le monde actuel, définitivement |
Réponse 202 : {data: {installId}}
GET /services/{code}/games/content/installs/{installId}
Permissions : games.content:read
status : queued, running, completed, failed, cancelled ; une installation terminée dont des dépendances manquent porte warning.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
installId | chemin | string | oui | installId de l'installation |
Réponse 200 : {data: {installId, status, step, progress, detail, cancellable, error, warning, ...}}
POST /services/{code}/games/content/installs/{installId}/cancel
Permissions : games.content:write
Tant que cancellable vaut true.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
installId | chemin | string | oui | installId de l'installation |
Réponse 200 : {data: {installId, status, ...}}
GET /services/{code}/games/content/installed
Permissions : games.content:read
Les fichiers .jar de /mods et /plugins, désactivés compris, avec leur source quand FreshPerf les a installés.
Réponse 200 : {data: {items: [{dir, fileName, baseName, enabled, size, provider, projectId, projectName, versionId, versionName, contentType}]}}
POST /services/{code}/games/content/installed/remove
Permissions : games.content:write
Supprime le fichier.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
dir | corps | string | oui | valeurs : /mods, /plugins |
fileName | corps | string | oui | fileName de la liste des fichiers installés |
Réponse 200 : {data: {removed}}
POST /services/{code}/games/content/installed/toggle
Permissions : games.content:write
S'applique au prochain démarrage.
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
dir | corps | string | oui | valeurs : /mods, /plugins |
fileName | corps | string | oui | |
enable | corps | boolean | oui |
Réponse 200 : {data: {fileName, enabled}}
Paramètres du jeu (Minecraft)
Exemple :
curl -s -X PATCH https://api.freshperf.fr/v1/services/SRV-TM8K2P-3317/games/settings \ -H "Authorization: Bearer $FRESHPERF_KEY" -H "Content-Type: application/json" \ -d '{"values": {"max-players": "40", "difficulty": "hard"}}'
{"data": {"changed": ["max-players", "difficulty"], "restartRequired": true, "confirmed": false, "settings": [{"key": "max-players", "type": "integer", "value": "40", "min": 1, "max": 10000}]}}
GET /services/{code}/games/settings
Permissions : games.settings:read
Serveurs Minecraft (409 SETTINGS_NOT_SUPPORTED sinon) : les clés de server.properties que cette version lit, typées (text, integer, boolean, enum) avec leurs bornes, et l'icône du serveur. Sur un proxy : supported: false avec reason: PROXY.
Réponse 200 : {data: {supported, generated, version, settings: [{key, type, value, options, min, max, maxLength}], icon}}
PATCH /services/{code}/games/settings
Permissions : games.settings:write
Seules les clés envoyées changent ; chaque valeur est vérifiée avant toute écriture (409 SETTING_REJECTED, SETTING_INVALID, ICON_INVALID). Sur un serveur démarré, le changement s'applique au prochain redémarrage (restartRequired). Envoyez au moins un des trois champs.
Code 409 | Quand |
|---|---|
SERVER_TRANSITIONING | le serveur démarre ou s'arrête |
SETTINGS_NOT_GENERATED | le serveur n'a pas encore créé server.properties |
EDIT_IN_PROGRESS | une autre modification du serveur est en cours |
INSTALL_IN_PROGRESS | une installation ou une extraction d'archive est en cours |
| Paramètre | Où | Type | Requis | Valeurs et format |
|---|---|---|---|---|
values | corps | objet | non | Clé -> valeur, clés tirées de settings[].key de GET /games/settings. online-mode demande services.console:write |
icon | corps | string | non | La nouvelle icône : base64 d'un PNG 64x64, 64 Kio au plus |
removeIcon | corps | boolean | non | Retirer l'icône ; pas avec icon |
Réponse 200 : {data: {settings, changed, restartRequired, confirmed, icon}}