Parcourir la documentation

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 :

SujetRègle
Enveloppe{"data": ...}. data porte les champs que chaque route liste ci-dessous
Listessous la clé que chaque route nomme (entries, rows, results, items...). Aucune pagination, sauf page et limit sur les recherches de catalogue
Champs des réponsesles 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 vide400 VALIDATION_ERROR:<champ>, avant tout appel au serveur
Refus du serveur409 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 actif409 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'actionschaque 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 jeuGET .../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
Dateschaî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

StatutQuand
200l'opération est faite, ou c'est une lecture
201création faite : POST .../files/directories, POST .../databases, POST .../schedules
202opération longue lancée. Le tableau ci-dessous dit quoi relire
Route qui répond 202RelisezJusqu'à
POST .../files/compress, .../files/decompress, .../world/exportGET .../files/jobs/{jobId} → job.statuscompleted, failed ou detached
POST .../world/import/extractGET .../world → staging.extractioncompleted ou failed
POST .../world/import/fetchGET .../world → staging.archivesl'archive est listée
POST .../versions/installsGET .../versions/installs/{installId} → statuscompleted ou failed
POST .../content/installsGET .../content/installs/{installId} → statuscompleted, failed ou cancelled
POST .../schedules/{scheduleId}/runGET .../schedules → rows[].isProcessingfalse

Relisez toutes les 2 à 5 secondes.

Idempotence

4 routes exigent l'en-tête Idempotency-Key :

RouteEffet
POST /services/{code}/games/databasescreate
POST /services/{code}/games/databases/{databaseId}/passwordrotate-password
POST /services/{code}/games/versions/installsinstall
POST /services/{code}/games/content/installsinstall

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

PermissionRoutes
services:readGET .../games/features
games.sftp:readGET .../games/sftp
games.files:readGET .../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:writePUT .../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:readGET .../games/databases
games.databases:writePOST .../games/databases, POST .../games/databases/{databaseId}/password, DELETE .../games/databases/{databaseId}
games.schedules:readGET .../games/schedules
games.schedules:writePOST .../games/schedules, PUT .../games/schedules/{scheduleId}, POST .../games/schedules/{scheduleId}/toggle, POST .../games/schedules/{scheduleId}/run, DELETE .../games/schedules/{scheduleId}
games.startup:readGET .../games/startup
games.startup:writePUT .../games/startup/variables/{key}, PUT .../games/startup/image
games.versions:readGET .../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:writePOST .../games/versions/installs
games.content:readGET .../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:writePOST .../games/content/installs, POST .../games/content/installs/{installId}/cancel, POST .../games/content/installed/remove, POST .../games/content/installed/toggle
games.settings:readGET .../games/settings
games.settings:writePATCH .../games/settings
services.console:writePOST .../games/schedules/{scheduleId}/run
services.power:writePOST .../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êteDemande 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 stopservices.power:write
armer une tâche (POST .../toggle avec isActive: true) ou la lancerservices.console:write et services.power:write
online-mode dans values de PATCH .../settingsservices.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.

stateSens
SYNCEDconnectez-vous avec le mot de passe du compte
UNSYNCEDle 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_PROVISIONEDl'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ètreOùTypeRequisValeurs et format
directoryrequêtestringnonDossier, / 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ètreOùTypeRequisValeurs et format
filerequêtestringouiChemin 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ètreOùTypeRequisValeurs et format
filecorpsstringouiChemin depuis la racine du serveur, par exemple /plugins/config.yml
contentcorpsstringnonLe 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier auquel les chemins sont relatifs, / par défaut
filescorpstableau de RenamePairoui

Chaque élément RenamePair :

ChampTypeRequisValeurs et format
fromstringoui
tostringoui

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ètreOùTypeRequisValeurs et format
locationcorpsstringouiChemin 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier auquel les noms sont relatifs, / par défaut
filescorpsstring[]ouiNoms 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier parent, / par défaut
namecorpsstringouiNom ; / 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier auquel les noms sont relatifs, / par défaut
filescorpstableau de ChmodEntryoui

Chaque élément ChmodEntry :

ChampTypeRequisValeurs et format
filestringouiNom dans root
modestringouiMode 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier auquel les noms sont relatifs, / par défaut
filescorpsstring[]ouiNoms dans root
namecorpsstringnonNom 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ètreOùTypeRequisValeurs et format
rootcorpsstringnonDossier de l'archive, / par défaut
filecorpsstringouiNom 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ètreOùTypeRequisValeurs et format
jobIdcheminstringouijobId 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_JAVAune édition autre que Java
PROXYun proxy
WORLD_CONTAINERles 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ètreOùTypeRequisValeurs et format
worldcorpsstringnonNom 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ètreOùTypeRequisValeurs et format
seedcorpsstringnonGraine (64 caractères au plus) ; aléatoire si absente ou vide
levelTypecorpsstringnonType de monde ; valeurs : normal, flat, large_biomes, amplified
keepBackupcorpsbooleannonGarder 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ètreOùTypeRequisValeurs et format
worldcorpsstringouiNom 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ètreOùTypeRequisValeurs et format
worldcorpsstringouiNom actuel du dossier
namecorpsstringouiNouveau 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ètreOùTypeRequisValeurs et format
worldcorpsstringouiNom 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ètreOùTypeRequisValeurs et format
queryrequêtestringnonTermes recherchés
pagerequêteintegernonPage, à partir de 0
limitrequêteintegernon1 à 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ètreOùTypeRequisValeurs et format
projectIdcheminstringouiprojectId 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ètreOùTypeRequisValeurs et format
projectIdcorpsstringouiprojectId de GET /games/world/catalog
fileIdcorpsstringouiversionId 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ètreOùTypeRequisValeurs et format
filecorpsstringouiNom 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ètreOùTypeRequisValeurs et format
filecorpsstringouiNom 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ètreOùTypeRequisValeurs et format
candidatecorpsstringnonstaging.candidates[].path de GET /games/world ; vide quand le dossier extrait est lui-même le monde
keepBackupcorpsbooleannonGarder 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ètreOùTypeRequisValeurs et format
namecorpsstringoui3 à 32 lettres, chiffres, _ ou -
remotecorpsstringnonHô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ètreOùTypeRequisValeurs et format
databaseIdcheminstringouiid 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ètreOùTypeRequisValeurs et format
databaseIdcheminstringouiid 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.

ChampSens quand il vaut false
editablela tâche contient ce que cette API n'écrit pas (une autre sorte d'étape, une valeur hors bornes)
armablela 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ètreOùTypeRequisValeurs et format
namecorpsstringoui1 à 60 caractères
minutecorpsstringnon0-59
hourcorpsstringnon0-23
dayOfMonthcorpsstringnon1-31
monthcorpsstringnon1-12
dayOfWeekcorpsstringnon0-7, 0 et 7 étant dimanche
isActivecorpsbooleannonArmée, true par défaut
stepscorpstableau de ScheduleStepoui1 à 10 étapes

Chaque élément ScheduleStep :

ChampTypeRequisValeurs et format
kindstringouivaleurs : command, restart, stop
commandstringnonCommande console (500 caractères au plus), pour command
offsetSecondsintegernonSecondes 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ètreOùTypeRequisValeurs et format
scheduleIdcheminintegerouiid de la tâche
namecorpsstringoui1 à 60 caractères
minutecorpsstringnon0-59
hourcorpsstringnon0-23
dayOfMonthcorpsstringnon1-31
monthcorpsstringnon1-12
dayOfWeekcorpsstringnon0-7, 0 et 7 étant dimanche
isActivecorpsbooleannonArmée, true par défaut
stepscorpstableau de ScheduleStepoui1 à 10 étapes

Chaque élément ScheduleStep :

ChampTypeRequisValeurs et format
kindstringouivaleurs : command, restart, stop
commandstringnonCommande console (500 caractères au plus), pour command
offsetSecondsintegernonSecondes 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ètreOùTypeRequisValeurs et format
scheduleIdcheminintegerouiid de la tâche
isActivecorpsbooleanoui

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ètreOùTypeRequisValeurs et format
scheduleIdcheminintegerouiid de la tâche

Réponse 202 : {data: {status: "queued"}}

DELETE /services/{code}/games/schedules/{scheduleId}

Permissions : games.schedules:write

ParamètreOùTypeRequisValeurs et format
scheduleIdcheminintegerouiid 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ètreOùTypeRequisValeurs et format
keycheminstringouienv de la variable
valuecorpsstringnonPour 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ètreOùTypeRequisValeurs et format
imagecorpsstringoui

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ètreOùTypeRequisValeurs et format
typecheminstringouiid 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ètreOùTypeRequisValeurs et format
typecheminstringouiid du logiciel
versioncheminstringouiversionId

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ètreOùTypeRequisValeurs et format
typecorpsstringouiid de GET /games/versions/types, par exemple PAPER
versioncorpsstringouiversionId de GET /games/versions/types/{type}/versions
buildIdcorpsstringnonid 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ètreOùTypeRequisValeurs et format
installIdcheminstringouiinstallId 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ètreOùTypeRequisValeurs et format
typerequêtestringnonmod (par défaut), plugin ou modpack
queryrequêtestringnonTermes recherchés
providerrequêtestringnonCette source seulement
gameVersionrequêtestringnonVersion du jeu, par exemple 1.21.4
loaderrequêtestringnonLoader, par exemple fabric
pagerequêteintegernonPage, à partir de 0
limitrequêteintegernon1 à 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ètreOùTypeRequisValeurs et format
providercheminstringouiprovider de la recherche
projectIdcheminstringouiprojectId 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ètreOùTypeRequisValeurs et format
providercheminstringouiprovider de la recherche
projectIdcheminstringouiprojectId de la recherche
gameVersionrequêtestringnonSeulement les versions pour cette version du jeu
loaderrequêtestringnonSeulement 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ètreOùTypeRequisValeurs et format
providercheminstringouiprovider de la recherche
projectIdcheminstringouiprojectId de la recherche
versionIdrequêtestringnonLa version installée
gameVersionrequêtestringnon
loaderrequêtestringnon
typerequêtestringnonmod, 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ètreOùTypeRequisValeurs et format
withLatestModpackrequêtebooleannonRendre 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ètreOùTypeRequisValeurs et format
providercorpsstringouiprovider des résultats de recherche
projectIdcorpsstringouiprojectId des résultats de recherche
versionIdcorpsstringouiversionId de GET .../projects/{provider}/{projectId}/versions
typecorpsstringnonmod par défaut ; valeurs : mod, plugin, modpack
projectNamecorpsstringnonNom affiché gardé avec le fichier installé
versionNamecorpsstringnonNom affiché de la version
gameVersioncorpsstringnon
loadercorpsstringnon
cleancorpsbooleannonModpacks : retirer d'abord le contenu du pack précédent
deleteWorldcorpsbooleannonModpacks : 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ètreOùTypeRequisValeurs et format
installIdcheminstringouiinstallId 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ètreOùTypeRequisValeurs et format
installIdcheminstringouiinstallId 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ètreOùTypeRequisValeurs et format
dircorpsstringouivaleurs : /mods, /plugins
fileNamecorpsstringouifileName 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ètreOùTypeRequisValeurs et format
dircorpsstringouivaleurs : /mods, /plugins
fileNamecorpsstringoui
enablecorpsbooleanoui

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 409Quand
SERVER_TRANSITIONINGle serveur démarre ou s'arrête
SETTINGS_NOT_GENERATEDle serveur n'a pas encore créé server.properties
EDIT_IN_PROGRESSune autre modification du serveur est en cours
INSTALL_IN_PROGRESSune installation ou une extraction d'archive est en cours
ParamètreOùTypeRequisValeurs et format
valuescorpsobjetnonClé -> valeur, clés tirées de settings[].key de GET /games/settings. online-mode demande services.console:write
iconcorpsstringnonLa nouvelle icône : base64 d'un PNG 64x64, 64 Kio au plus
removeIconcorpsbooleannonRetirer l'icône ; pas avec icon

Réponse 200 : {data: {settings, changed, restartRequired, confirmed, icon}}