Browse the documentation

Game servers

The routes of this page drive a game server. They live under /v1/services/{code}/games and all take the service code (SRV-TM8K2P-3317), from GET /services. A service of another type (VPS, web hosting) answers 409 SERVICE_TYPE_NOT_SUPPORTED.

The other identifiers come from the list routes: jobId of an archive job, databaseId from GET .../games/databases, scheduleId from GET .../games/schedules (an integer), installId of an install. They are opaque: do not build them.

Conventions of these routes

The general rules of Requests and responses apply. What changes here:

TopicRule
Envelope{"data": ...}. data carries the fields each route lists below
Listsunder the key each route names (entries, rows, results, items...). No pagination, except page and limit on the catalogue searches
Response fieldsthe responses on this page list the guaranteed fields. A response may carry others: ignore the ones you do not know
Required field absent or blank400 VALIDATION_ERROR:<field>, before anything reaches the server
Server refusal409 with an upper-case code (FILES_BUSY, SERVER_NOT_STOPPED, SCHEDULE_LIMIT_REACHED...). A code ending in _BUSY carries Retry-After: 5. A value refused without a code (a path with ..) answers 502 ACTION_FAILED
Suspended or no longer active service409 SERVICE_NOT_ACTIVE on every route, reads included, except GET .../games/features and GET .../games/sftp
Server not created yet409 INSTANCE_NOT_PROVISIONED
Action budgetevery call spends the account's action budget, shared with the dashboard (Rate limits and idempotency). Past it: 429 API_RATE_LIMITED with Retry-After
Depending on the gameGET .../games/features says what the server offers. Worlds and game settings are Minecraft only: 409 WORLD_NOT_SUPPORTED, 409 SETTINGS_NOT_SUPPORTED elsewhere
DatesISO 8601 strings with their offset, except current.installedAt of GET .../games/versions and startedAt / updatedAt of content installs, without one, and info.lastPlayed of worlds, an integer in epoch milliseconds

Success statuses

StatusWhen
200the operation is done, or it is a read
201created: POST .../files/directories, POST .../databases, POST .../schedules
202a long operation started. The table below says what to poll
Route answering 202PollUntil
POST .../files/compress, .../files/decompress, .../world/exportGET .../files/jobs/{jobId} → job.statuscompleted, failed or detached
POST .../world/import/extractGET .../world → staging.extractioncompleted or failed
POST .../world/import/fetchGET .../world → staging.archivesthe archive is listed
POST .../versions/installsGET .../versions/installs/{installId} → statuscompleted or failed
POST .../content/installsGET .../content/installs/{installId} → statuscompleted, failed or cancelled
POST .../schedules/{scheduleId}/runGET .../schedules → rows[].isProcessingfalse

Poll every 2 to 5 seconds.

Idempotency

4 routes require the Idempotency-Key header:

RouteEffect
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

Passwords answered once

POST .../databases and POST .../databases/{databaseId}/password answer the database password, once. GET .../databases never returns it, and a replay of the same Idempotency-Key answers the database without it, with credentialsRedacted: true. The SFTP password is your FreshPerf account password: no route returns it.

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

A :write gives the :read of the same name. Two permissions are added by what the request holds:

RequestAlso needs
a scheduled task with a command step (create, change)services.console:write
a scheduled task with a restart or stop stepservices.power:write
arming a task (POST .../toggle with isActive: true) or running itservices.console:write and services.power:write
online-mode in values of PATCH .../settingsservices.console:write

Without it: 403 API_SCOPE_MISSING:<permission>. On an account shared with you, the access must grant you the matching permission on the service (files, SFTP, databases, scheduled tasks, startup, versions, content, game settings), plus console and power in the cases above.

Outside the API

These stay in the dashboard: uploading and downloading files (use SFTP), downloading a file from a web address, players, ports and subdomains. Console, power and reinstall are in Managing services.

Server features

GET /services/{code}/games/features

Permissions: services:read

What this game server offers beyond files, databases, scheduled tasks and startup, from its game: sftp, versions, content, world, game-settings (the settings routes). It may also list players and subdomains, which stay in the dashboard. gameType is minecraft on a Minecraft server. Answers on a suspended service too.

Response 200: {data: {features: [{id, label}], gameType}}

GET /services/{code}/games/sftp

Permissions: games.sftp:read

The username, host and port to connect with. The password is the FreshPerf account password of the key's holder, never returned. Answers on a suspended service too.

stateMeaning
SYNCEDconnect with the account password
UNSYNCEDthe account password is not active on SFTP yet: log in to the dashboard again or change your password
NOT_PROVISIONEDthe access of a shared account's holder is being set up. The response carries state only: read again in a moment

Response 200: {data: {username, host, port, state}}

Files

Example:

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

Entries of the directory. 409 FILES_BUSY when too many slow file operations (list, copy, delete) already run: retry.

ParameterInTypeRequiredValues and format
directoryquerystringnoDirectory, default /

Response 200: {data: {entries: [{name, mode, modeBits, size, isFile, isSymlink, mimetype, modifiedAt}]}}

GET /services/{code}/games/files/content

Permissions: games.files:read

A text file's content. A binary file does not survive the trip: read archives and jars through SFTP.

ParameterInTypeRequiredValues and format
filequerystringyesPath from the server's root

Response 200: {data: {content}}

PUT /services/{code}/games/files/content

Permissions: games.files:write

Creates the file or replaces its content.

ParameterInTypeRequiredValues and format
filebodystringyesPath from the server's root, e.g. /plugins/config.yml
contentbodystringnoThe new content (text); empty when absent

Response 200: {data: {status}}

POST /services/{code}/games/files/rename

Permissions: games.files:write

Each pair is relative to root; a to in another directory moves the file.

ParameterInTypeRequiredValues and format
rootbodystringnoDirectory the paths are relative to, default /
filesbodyarray of RenamePairyes

Each RenamePair item:

FieldTypeRequiredValues and format
fromstringyes
tostringyes

Response 200: {data: {renamed}}

POST /services/{code}/games/files/copy

Permissions: games.files:write

The copy is created next to the file. 409 FILES_BUSY as for the listing.

ParameterInTypeRequiredValues and format
locationbodystringyesPath of the file to copy

Response 200: {data: {status}}

POST /services/{code}/games/files/delete

Permissions: games.files:write

Deletes files and directories with their content, irreversibly. 409 FILES_BUSY as for the listing.

ParameterInTypeRequiredValues and format
rootbodystringnoDirectory the names are relative to, default /
filesbodystring[]yesNames or paths inside root

Response 200: {data: {deleted}}

POST /services/{code}/games/files/directories

Permissions: games.files:write

Nested directories are created as needed.

ParameterInTypeRequiredValues and format
rootbodystringnoParent directory, default /
namebodystringyesName, / allowed for nested directories

Response 201: {data: {status}}

POST /services/{code}/games/files/chmod

Permissions: games.files:write

Octal modes, e.g. 644.

ParameterInTypeRequiredValues and format
rootbodystringnoDirectory the names are relative to, default /
filesbodyarray of ChmodEntryyes

Each ChmodEntry item:

FieldTypeRequiredValues and format
filestringyesName inside root
modestringyesOctal mode, e.g. 644

Response 200: {data: {chmoded}}

POST /services/{code}/games/files/compress

Permissions: games.files:write

Starts a .tar.gz archive of the files inside root and answers 202 with the job: poll GET .../files/jobs/{jobId}. One archive job at a time per server (409 ARCHIVE_ALREADY_RUNNING); ARCHIVE_NAME_TAKEN, ARCHIVE_NAME_INVALID for a bad name.

ParameterInTypeRequiredValues and format
rootbodystringnoDirectory the names are relative to, default /
filesbodystring[]yesNames inside root
namebodystringnoArchive name; .tar.gz is appended when missing. A generated name when absent

Response 202: {data: {job: {jobId, kind, status, root, entryCount, requestedName, name, sizeBytes, error}}}; kind is compress or extract

POST /services/{code}/games/files/decompress

Permissions: games.files:write

Starts extracting the archive into its directory and answers 202 with the job: poll GET .../files/jobs/{jobId}. It shares the one archive job per server with compression (409 ARCHIVE_ALREADY_RUNNING).

ParameterInTypeRequiredValues and format
rootbodystringnoDirectory holding the archive, default /
filebodystringyesArchive name inside root (one name, no /)

Response 202: {data: {job: {...}}}

GET /services/{code}/games/files/jobs

Permissions: games.files:read

The archive or extraction job running on the server, or null.

Response 200: {data: {job}}

GET /services/{code}/games/files/jobs/{jobId}

Permissions: games.files:read

status: queued, running, completed, failed or detached. detached no longer changes: the operation goes on on the server without tracking: a compression leaves its archive there under a generated name instead of the one asked for, an extraction keeps writing its files. Read the directory (GET .../files) to see the result.

ParameterInTypeRequiredValues and format
jobIdpathstringyesjobId of the job

Response 200: {data: {job: {...}}}

Worlds (Minecraft)

GET /services/{code}/games/world

Permissions: games.files:read

Minecraft servers (409 WORLD_NOT_SUPPORTED otherwise): the worlds, the active one (levelName), the archives in the server's root, the import area and the job running.

reason (with supported: false)Case
NOT_JAVAan edition other than Java
PROXYa proxy
WORLD_CONTAINERthe worlds are kept in another folder, named by container

With NOT_JAVA or PROXY, every other world route except GET .../world and the two GET .../world/catalog routes answers 409 WORLD_NOT_SUPPORTED; with WORLD_CONTAINER, the ones that export, regenerate, activate, rename, delete or apply a world (import/apply). staging.extraction is none, running, completed, failed or unsettled (the extraction goes on without tracking: read again).

Response 200: {data: {supported, levelName, worlds: [...], archives: [...], staging, job, busy, ...}}

POST /services/{code}/games/world/export

Permissions: games.files:write

Starts an archive of the world into the server's root and answers 202 with the job (poll GET .../files/jobs/{jobId}). On a running server the world is saved first (save-all flush). 409 SERVER_TRANSITIONING while the server starts or stops.

ParameterInTypeRequiredValues and format
worldbodystringnoWorld folder name; the active world when absent

Response 202: {data: {job, archive, running, saved}}

POST /services/{code}/games/world/reset

Permissions: games.files:write

Replaces the active world by a new one. The server must be stopped (409 SERVER_NOT_STOPPED). The old world is kept as a backup folder unless keepBackup is false.

ParameterInTypeRequiredValues and format
seedbodystringnoSeed (64 characters at most); a random one when absent or empty
levelTypebodystringnoWorld type; values: normal, flat, large_biomes, amplified
keepBackupbodybooleannoKeep the current world as a backup folder, default true. false deletes it

Response 200: {data: {backup, confirmed}}

POST /services/{code}/games/world/activate

Permissions: games.files:write

Points the server at another world folder. The server must be stopped.

ParameterInTypeRequiredValues and format
worldbodystringyesWorld folder name

Response 200: {data: {backup, confirmed}}

POST /services/{code}/games/world/rename

Permissions: games.files:write

Not the active world (409 WORLD_IS_ACTIVE). The server must be stopped.

ParameterInTypeRequiredValues and format
worldbodystringyesCurrent folder name
namebodystringyesNew folder name

Response 200: {data: {backup, confirmed}}

POST /services/{code}/games/world/delete

Permissions: games.files:write

Not the active world. Deleted irreversibly. The server must be stopped.

ParameterInTypeRequiredValues and format
worldbodystringyesWorld folder name

Response 200: {data: {backup, confirmed}}

GET /services/{code}/games/world/catalog

Permissions: games.files:read

Maps to download (409 WORLD_CATALOG_UNAVAILABLE when the catalogue is off).

ParameterInTypeRequiredValues and format
queryquerystringnoSearch terms
pagequeryintegernoPage, from 0
limitqueryintegerno1 to 50, default 20

Response 200: {data: {results: [{provider, projectId, name, author, description, iconUrl, downloads, type}]}}

GET /services/{code}/games/world/catalog/{projectId}/files

Permissions: games.files:read

The downloadable versions of a catalogue world.

ParameterInTypeRequiredValues and format
projectIdpathstringyesprojectId of the search

Response 200: {data: {versions: [{versionId, name, gameVersions, fileName, fileSize, available, ...}]}}

POST /services/{code}/games/world/import/fetch

Permissions: games.files:write

The server downloads the file into the import area and answers 202; GET /games/world shows it in staging once there. Extract it next.

ParameterInTypeRequiredValues and format
projectIdbodystringyesprojectId of GET /games/world/catalog
fileIdbodystringyesversionId of GET /games/world/catalog/{projectId}/files

Response 202: {data: {status, file, expectedSize}}

POST /services/{code}/games/world/import/stage

Permissions: games.files:write

Moves an archive of the server's root (an export, an archive you made) into the import area.

ParameterInTypeRequiredValues and format
filebodystringyesArchive name

Response 200: {data: {file}}

POST /services/{code}/games/world/import/extract

Permissions: games.files:write

Answers 202 with the extraction job; GET /games/world then lists the worlds found in it (staging.candidates).

ParameterInTypeRequiredValues and format
filebodystringyesArchive name

Response 202: {data: {job}}

POST /services/{code}/games/world/import/apply

Permissions: games.files:write

Replaces the active world by the imported one. The server must be stopped. The replaced world is kept as a backup folder unless keepBackup is false.

ParameterInTypeRequiredValues and format
candidatebodystringnostaging.candidates[].path of GET /games/world; empty when the extracted folder itself is the world
keepBackupbodybooleannoKeep the replaced world as a backup folder, default true

Response 200: {data: {backup, confirmed}}

DELETE /services/{code}/games/world/import

Permissions: games.files:write

Empties the import area; a staged archive goes back to the server's root.

Response 200: {data: {}}

Databases

Example:

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

Connection details without passwords: a password is shown once, when the database is created or its password reset. limit is the offer's quota, null when the offer sets none.

Response 200: {data: {rows: [{id, name, host, port, username, connectionsFrom, maxConnections}], limit}}; maxConnections is null or 0 when unlimited

POST /services/{code}/games/databases

Permissions: games.databases:write · Header: Idempotency-Key

Answers the database with its password, once: a replay of the same Idempotency-Key answers it without (credentialsRedacted). 409 DATABASE_QUOTA_REACHED, DATABASE_INVALID_NAME, DATABASE_INVALID_REMOTE.

ParameterInTypeRequiredValues and format
namebodystringyes3 to 32 letters, digits, _ or -
remotebodystringnoHosts allowed to connect, default % (any)

Response 201: {data: {database: {id, name, host, port, username, connectionsFrom, maxConnections, password}}}

POST /services/{code}/games/databases/{databaseId}/password

Permissions: games.databases:write · Header: Idempotency-Key

A new password, answered once; the old one stops working. At most 10 a minute per account, 429 API_RATE_LIMITED past that.

ParameterInTypeRequiredValues and format
databaseIdpathstringyesid of the database

Response 200: {data: {database: {..., password}}}

DELETE /services/{code}/games/databases/{databaseId}

Permissions: games.databases:write

With its data, irreversibly.

ParameterInTypeRequiredValues and format
databaseIdpathstringyesid of the database

Response 200: {data: {status}}

Scheduled tasks

Example:

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

With the limits (limits: 10 tasks, 10 steps, 900 seconds of offset) and the timezone (timezone) the cron fields are read in.

FieldMeaning when false
editablethe task holds something this API does not write (another kind of step, a value out of bounds)
armablethe task can be paused or deleted, but neither armed nor run (409 SCHEDULE_READ_ONLY) until a PUT saves it again

Response 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

A command step also needs services.console:write, a restart or stop step services.power:write. A task fires only while the server is running. 409 SCHEDULE_LIMIT_REACHED, SCHEDULE_TOO_MANY_STEPS, SCHEDULE_INVALID_*, SCHEDULE_REJECTED.

Cron fields: * when absent or empty. Each takes *, a value, a range (1-5), a list (1,15) and a step over * or a range (*/15).

ParameterInTypeRequiredValues and format
namebodystringyes1 to 60 characters
minutebodystringno0-59
hourbodystringno0-23
dayOfMonthbodystringno1-31
monthbodystringno1-12
dayOfWeekbodystringno0-7, 0 and 7 being Sunday
isActivebodybooleannoArmed, default true
stepsbodyarray of ScheduleStepyes1 to 10 steps

Each ScheduleStep item:

FieldTypeRequiredValues and format
kindstringyesvalues: command, restart, stop
commandstringnoConsole command (500 characters at most), for command
offsetSecondsintegernoSeconds after the previous step, 0 to 900, default 0

Response 201: {data: {status: "created"}}

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

Permissions: games.schedules:write

Replaces the task: send every field. Same extra permissions, rules and refusals as a creation, except SCHEDULE_LIMIT_REACHED. 409 SCHEDULE_BUSY while it runs, SCHEDULE_NOT_FOUND for an unknown scheduleId.

ParameterInTypeRequiredValues and format
scheduleIdpathintegeryesid of the task
namebodystringyes1 to 60 characters
minutebodystringno0-59
hourbodystringno0-23
dayOfMonthbodystringno1-31
monthbodystringno1-12
dayOfWeekbodystringno0-7, 0 and 7 being Sunday
isActivebodybooleannoArmed, default true
stepsbodyarray of ScheduleStepyes1 to 10 steps

Each ScheduleStep item:

FieldTypeRequiredValues and format
kindstringyesvalues: command, restart, stop
commandstringnoConsole command (500 characters at most), for command
offsetSecondsintegernoSeconds after the previous step, 0 to 900, default 0

Response 200: {data: {status: "updated"}}

POST /services/{code}/games/schedules/{scheduleId}/toggle

Permissions: games.schedules:write

Arming a task is firing it at its next tick: it also needs services.console:write and services.power:write. Pausing needs nothing more. 409 SCHEDULE_READ_ONLY to arm a task with armable: false.

ParameterInTypeRequiredValues and format
scheduleIdpathintegeryesid of the task
isActivebodybooleanyes

Response 200: {data: {status: "active"|"paused"}}

POST /services/{code}/games/schedules/{scheduleId}/run

Permissions: games.schedules:write, services.console:write, services.power:write

Runs its commands and power steps now. 409 SCHEDULE_INACTIVE on a paused task, SCHEDULE_BUSY while it runs, SCHEDULE_READ_ONLY on a task with armable: false, INSTALL_IN_PROGRESS during an install.

ParameterInTypeRequiredValues and format
scheduleIdpathintegeryesid of the task

Response 202: {data: {status: "queued"}}

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

Permissions: games.schedules:write

ParameterInTypeRequiredValues and format
scheduleIdpathintegeryesid of the task

Response 200: {data: {status: "deleted"}}

Startup

GET /services/{code}/games/startup

Permissions: games.startup:read

The variables this server lets you change (widget: text, select, number, boolean) and, when the game offers a choice, the runtime image; runtime is null otherwise. label and description are objects keyed by locale (fr-fr, en-us).

Response 200: {data: {fields: [{env, value, rules, label, description, widget, options, ...}], runtime: {current, options, ...}}}

PUT /services/{code}/games/startup/variables/{key}

Permissions: games.startup:write

Applies at the next start. 409 VARIABLE_REJECTED for a variable not offered or a value refused, INSTALL_IN_PROGRESS during an install.

ParameterInTypeRequiredValues and format
keypathstringyesenv of the variable
valuebodystringnoFor a list variable, one of its options; empty when absent

Response 200: {data: {value}}

PUT /services/{code}/games/startup/image

Permissions: games.startup:write

One of runtime.options; applies at the next start, nothing is reinstalled. 409 INVALID_DOCKER_IMAGE for a value outside runtime.options, INSTALL_IN_PROGRESS during an install.

ParameterInTypeRequiredValues and format
imagebodystringyes

Response 200: {data: {image}}

Server software

Example:

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

What FreshPerf last installed (current) and the install running now (active). Each is null when there is none.

Response 200: {data: {active, current: {type, versionId, build, java, installedAt}}}

GET /services/{code}/games/versions/types

Permissions: games.versions:read

Vanilla, Paper, Fabric, Forge...

Response 200: {data: {types: [{id, name, category, description, deprecated, experimental, ...}]}}

GET /services/{code}/games/versions/types/{type}/versions

Permissions: games.versions:read

ParameterInTypeRequiredValues and format
typepathstringyesid of the software

Response 200: {data: {versions: [{versionId, releaseType, java, supported, builds, latestBuildId, latestBuildName}]}}

GET /services/{code}/games/versions/types/{type}/versions/{version}/builds

Permissions: games.versions:read

ParameterInTypeRequiredValues and format
typepathstringyesid of the software
versionpathstringyesversionId

Response 200: {data: {builds: [{id, name, buildNumber, created, experimental}]}}

POST /services/{code}/games/versions/installs

Permissions: games.versions:write · Header: Idempotency-Key

Stops the server, installs the software, switches the runtime to its Java and starts the server again. Answers 202 with installId: poll GET .../versions/installs/{installId}. 409 INSTALL_IN_PROGRESS and the other *_IN_PROGRESS while something else runs, SCHEDULE_RUNNING while a scheduled task runs.

ParameterInTypeRequiredValues and format
typebodystringyesid of GET /games/versions/types, e.g. PAPER
versionbodystringyesversionId of GET /games/versions/types/{type}/versions
buildIdbodystringnoid of the builds list; the latest build when absent

Response 202: {data: {installId}}

GET /services/{code}/games/versions/installs/{installId}

Permissions: games.versions:read

status: queued, running, completed, failed; step and progress (0-100) while it runs. step: QUEUED, STOPPING, CLEANING, DOWNLOADING, INSTALLING, UPDATING_RUNTIME, CONFIGURING, STARTING, DONE, ERROR. error is present after a failure only.

ParameterInTypeRequiredValues and format
installIdpathstringyesinstallId of the install

Response 200: {data: {installId, status, step, progress, type, versionId, build, error}}

Mods, plugins and modpacks

GET /services/{code}/games/content/providers

Permissions: games.content:read

Modrinth, CurseForge, Hangar, Spigot, as enabled, with the types each offers.

Response 200: {data: {providers: [{id, name, supportedTypes}]}}

GET /services/{code}/games/content/context

Permissions: games.content:read

From the last version FreshPerf installed: what to filter the search on.

Response 200: {data: {hasContext, gameVersion, loader, software}}

GET /services/{code}/games/content/search

Permissions: games.content:read

ParameterInTypeRequiredValues and format
typequerystringnomod (default), plugin or modpack
queryquerystringnoSearch terms
providerquerystringnoOnly this source
gameVersionquerystringnoGame version, e.g. 1.21.4
loaderquerystringnoLoader, e.g. fabric
pagequeryintegernoPage, from 0
limitqueryintegerno1 to 50, default 20

Response 200: {data: {results: [{provider, projectId, name, author, description, iconUrl, downloads, type}]}}

GET /services/{code}/games/content/projects/{provider}/{projectId}

Permissions: games.content:read

ParameterInTypeRequiredValues and format
providerpathstringyesprovider of the search
projectIdpathstringyesprojectId of the search

Response 200: {data: {project: {provider, projectId, name, author, description, gameVersions, loaders, ...}}}

GET /services/{code}/games/content/projects/{provider}/{projectId}/versions

Permissions: games.content:read

ParameterInTypeRequiredValues and format
providerpathstringyesprovider of the search
projectIdpathstringyesprojectId of the search
gameVersionquerystringnoOnly versions for this game version
loaderquerystringnoOnly versions for this loader

Response 200: {data: {versions: [{versionId, name, gameVersions, loaders, fileName, fileSize, releaseType, datePublished}]}}

GET /services/{code}/games/content/projects/{provider}/{projectId}/update

Permissions: games.content:read

Whether a newer version than versionId fits the game version and loader.

ParameterInTypeRequiredValues and format
providerpathstringyesprovider of the search
projectIdpathstringyesprojectId of the search
versionIdquerystringnoThe installed version
gameVersionquerystringno
loaderquerystringno
typequerystringnomod, plugin or modpack

Response 200: {data: {updateAvailable, latest}}

GET /services/{code}/games/content/installs

Permissions: games.content:read

The install running now, or null; with withLatestModpack=true, the last modpack install too.

ParameterInTypeRequiredValues and format
withLatestModpackquerybooleannoAlso answer the last modpack install

Response 200: {data: {active, latestModpack}}

POST /services/{code}/games/content/installs

Permissions: games.content:write · Header: Idempotency-Key

Answers 202 with installId: poll GET .../content/installs/{installId}. A modpack stops and restarts the server; deleteWorld deletes the current world irreversibly. 409 INSTALL_IN_PROGRESS and the other *_IN_PROGRESS while something else runs; for a modpack, SCHEDULE_RUNNING while a scheduled task runs.

ParameterInTypeRequiredValues and format
providerbodystringyesprovider of the search results
projectIdbodystringyesprojectId of the search results
versionIdbodystringyesversionId of GET .../projects/{provider}/{projectId}/versions
typebodystringnoDefault mod; values: mod, plugin, modpack
projectNamebodystringnoDisplay name kept with the installed file
versionNamebodystringnoDisplay name of the version
gameVersionbodystringno
loaderbodystringno
cleanbodybooleannoModpacks: remove the previous pack's content first
deleteWorldbodybooleannoModpacks: delete the current world, irreversibly

Response 202: {data: {installId}}

GET /services/{code}/games/content/installs/{installId}

Permissions: games.content:read

status: queued, running, completed, failed, cancelled; a completed install whose dependencies are missing carries warning.

ParameterInTypeRequiredValues and format
installIdpathstringyesinstallId of the install

Response 200: {data: {installId, status, step, progress, detail, cancellable, error, warning, ...}}

POST /services/{code}/games/content/installs/{installId}/cancel

Permissions: games.content:write

While cancellable is true.

ParameterInTypeRequiredValues and format
installIdpathstringyesinstallId of the install

Response 200: {data: {installId, status, ...}}

GET /services/{code}/games/content/installed

Permissions: games.content:read

The .jar files of /mods and /plugins, disabled ones included, with their source when FreshPerf installed them.

Response 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

Deletes the file.

ParameterInTypeRequiredValues and format
dirbodystringyesvalues: /mods, /plugins
fileNamebodystringyesfileName of the installed list

Response 200: {data: {removed}}

POST /services/{code}/games/content/installed/toggle

Permissions: games.content:write

Applies at the next start.

ParameterInTypeRequiredValues and format
dirbodystringyesvalues: /mods, /plugins
fileNamebodystringyes
enablebodybooleanyes

Response 200: {data: {fileName, enabled}}

Game settings (Minecraft)

Example:

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

Minecraft servers (409 SETTINGS_NOT_SUPPORTED otherwise): the server.properties keys this release reads, typed (text, integer, boolean, enum) with their bounds, and the server icon. On a proxy: supported: false with reason: PROXY.

Response 200: {data: {supported, generated, version, settings: [{key, type, value, options, min, max, maxLength}], icon}}

PATCH /services/{code}/games/settings

Permissions: games.settings:write

Only the keys sent change; every value is checked before anything is written (409 SETTING_REJECTED, SETTING_INVALID, ICON_INVALID). On a running server the change applies at the next restart (restartRequired). Send at least one of the three fields.

409 codeWhen
SERVER_TRANSITIONINGthe server is starting or stopping
SETTINGS_NOT_GENERATEDthe server has not created server.properties yet
EDIT_IN_PROGRESSanother change to the server is in progress
INSTALL_IN_PROGRESSan install or an archive extraction is in progress
ParameterInTypeRequiredValues and format
valuesbodyobjectnoSetting key -> value, keys from settings[].key of GET /games/settings. online-mode needs services.console:write
iconbodystringnoThe new icon: base64 of a 64x64 PNG, 64 KiB at most
removeIconbodybooleannoRemove the icon; not with icon

Response 200: {data: {settings, changed, restartRequired, confirmed, icon}}