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:
| Topic | Rule |
|---|---|
| Envelope | {"data": ...}. data carries the fields each route lists below |
| Lists | under the key each route names (entries, rows, results, items...). No pagination, except page and limit on the catalogue searches |
| Response fields | the responses on this page list the guaranteed fields. A response may carry others: ignore the ones you do not know |
| Required field absent or blank | 400 VALIDATION_ERROR:<field>, before anything reaches the server |
| Server refusal | 409 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 service | 409 SERVICE_NOT_ACTIVE on every route, reads included, except GET .../games/features and GET .../games/sftp |
| Server not created yet | 409 INSTANCE_NOT_PROVISIONED |
| Action budget | every 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 game | GET .../games/features says what the server offers. Worlds and game settings are Minecraft only: 409 WORLD_NOT_SUPPORTED, 409 SETTINGS_NOT_SUPPORTED elsewhere |
| Dates | ISO 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
| Status | When |
|---|---|
200 | the operation is done, or it is a read |
201 | created: POST .../files/directories, POST .../databases, POST .../schedules |
202 | a long operation started. The table below says what to poll |
Route answering 202 | Poll | Until |
|---|---|---|
POST .../files/compress, .../files/decompress, .../world/export | GET .../files/jobs/{jobId} → job.status | completed, failed or detached |
POST .../world/import/extract | GET .../world → staging.extraction | completed or failed |
POST .../world/import/fetch | GET .../world → staging.archives | the archive is listed |
POST .../versions/installs | GET .../versions/installs/{installId} → status | completed or failed |
POST .../content/installs | GET .../content/installs/{installId} → status | completed, failed or cancelled |
POST .../schedules/{scheduleId}/run | GET .../schedules → rows[].isProcessing | false |
Poll every 2 to 5 seconds.
Idempotency
4 routes require the Idempotency-Key header:
| Route | Effect |
|---|---|
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 |
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
| 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 |
A :write gives the :read of the same name. Two permissions are added by what the request holds:
| Request | Also needs |
|---|---|
a scheduled task with a command step (create, change) | services.console:write |
a scheduled task with a restart or stop step | services.power:write |
arming a task (POST .../toggle with isActive: true) or running it | services.console:write and services.power:write |
online-mode in values of PATCH .../settings | services.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.
state | Meaning |
|---|---|
SYNCED | connect with the account password |
UNSYNCED | the account password is not active on SFTP yet: log in to the dashboard again or change your password |
NOT_PROVISIONED | the 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
directory | query | string | no | Directory, 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
file | query | string | yes | Path 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
file | body | string | yes | Path from the server's root, e.g. /plugins/config.yml |
content | body | string | no | The 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Directory the paths are relative to, default / |
files | body | array of RenamePair | yes |
Each RenamePair item:
| Field | Type | Required | Values and format |
|---|---|---|---|
from | string | yes | |
to | string | yes |
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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
location | body | string | yes | Path 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Directory the names are relative to, default / |
files | body | string[] | yes | Names or paths inside root |
Response 200: {data: {deleted}}
POST /services/{code}/games/files/directories
Permissions: games.files:write
Nested directories are created as needed.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Parent directory, default / |
name | body | string | yes | Name, / allowed for nested directories |
Response 201: {data: {status}}
POST /services/{code}/games/files/chmod
Permissions: games.files:write
Octal modes, e.g. 644.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Directory the names are relative to, default / |
files | body | array of ChmodEntry | yes |
Each ChmodEntry item:
| Field | Type | Required | Values and format |
|---|---|---|---|
file | string | yes | Name inside root |
mode | string | yes | Octal 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Directory the names are relative to, default / |
files | body | string[] | yes | Names inside root |
name | body | string | no | Archive 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).
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
root | body | string | no | Directory holding the archive, default / |
file | body | string | yes | Archive 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
jobId | path | string | yes | jobId 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_JAVA | an edition other than Java |
PROXY | a proxy |
WORLD_CONTAINER | the 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
world | body | string | no | World 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
seed | body | string | no | Seed (64 characters at most); a random one when absent or empty |
levelType | body | string | no | World type; values: normal, flat, large_biomes, amplified |
keepBackup | body | boolean | no | Keep 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
world | body | string | yes | World 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
world | body | string | yes | Current folder name |
name | body | string | yes | New 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
world | body | string | yes | World 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).
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
query | query | string | no | Search terms |
page | query | integer | no | Page, from 0 |
limit | query | integer | no | 1 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
projectId | path | string | yes | projectId 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
projectId | body | string | yes | projectId of GET /games/world/catalog |
fileId | body | string | yes | versionId 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
file | body | string | yes | Archive 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).
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
file | body | string | yes | Archive 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
candidate | body | string | no | staging.candidates[].path of GET /games/world; empty when the extracted folder itself is the world |
keepBackup | body | boolean | no | Keep 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
name | body | string | yes | 3 to 32 letters, digits, _ or - |
remote | body | string | no | Hosts 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
databaseId | path | string | yes | id of the database |
Response 200: {data: {database: {..., password}}}
DELETE /services/{code}/games/databases/{databaseId}
Permissions: games.databases:write
With its data, irreversibly.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
databaseId | path | string | yes | id 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.
| Field | Meaning when false |
|---|---|
editable | the task holds something this API does not write (another kind of step, a value out of bounds) |
armable | the 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).
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
name | body | string | yes | 1 to 60 characters |
minute | body | string | no | 0-59 |
hour | body | string | no | 0-23 |
dayOfMonth | body | string | no | 1-31 |
month | body | string | no | 1-12 |
dayOfWeek | body | string | no | 0-7, 0 and 7 being Sunday |
isActive | body | boolean | no | Armed, default true |
steps | body | array of ScheduleStep | yes | 1 to 10 steps |
Each ScheduleStep item:
| Field | Type | Required | Values and format |
|---|---|---|---|
kind | string | yes | values: command, restart, stop |
command | string | no | Console command (500 characters at most), for command |
offsetSeconds | integer | no | Seconds 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
scheduleId | path | integer | yes | id of the task |
name | body | string | yes | 1 to 60 characters |
minute | body | string | no | 0-59 |
hour | body | string | no | 0-23 |
dayOfMonth | body | string | no | 1-31 |
month | body | string | no | 1-12 |
dayOfWeek | body | string | no | 0-7, 0 and 7 being Sunday |
isActive | body | boolean | no | Armed, default true |
steps | body | array of ScheduleStep | yes | 1 to 10 steps |
Each ScheduleStep item:
| Field | Type | Required | Values and format |
|---|---|---|---|
kind | string | yes | values: command, restart, stop |
command | string | no | Console command (500 characters at most), for command |
offsetSeconds | integer | no | Seconds 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
scheduleId | path | integer | yes | id of the task |
isActive | body | boolean | yes |
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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
scheduleId | path | integer | yes | id of the task |
Response 202: {data: {status: "queued"}}
DELETE /services/{code}/games/schedules/{scheduleId}
Permissions: games.schedules:write
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
scheduleId | path | integer | yes | id 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
key | path | string | yes | env of the variable |
value | body | string | no | For 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
image | body | string | yes |
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
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
type | path | string | yes | id 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
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
type | path | string | yes | id of the software |
version | path | string | yes | versionId |
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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
type | body | string | yes | id of GET /games/versions/types, e.g. PAPER |
version | body | string | yes | versionId of GET /games/versions/types/{type}/versions |
buildId | body | string | no | id 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
installId | path | string | yes | installId 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
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
type | query | string | no | mod (default), plugin or modpack |
query | query | string | no | Search terms |
provider | query | string | no | Only this source |
gameVersion | query | string | no | Game version, e.g. 1.21.4 |
loader | query | string | no | Loader, e.g. fabric |
page | query | integer | no | Page, from 0 |
limit | query | integer | no | 1 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
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
provider | path | string | yes | provider of the search |
projectId | path | string | yes | projectId 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
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
provider | path | string | yes | provider of the search |
projectId | path | string | yes | projectId of the search |
gameVersion | query | string | no | Only versions for this game version |
loader | query | string | no | Only 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
provider | path | string | yes | provider of the search |
projectId | path | string | yes | projectId of the search |
versionId | query | string | no | The installed version |
gameVersion | query | string | no | |
loader | query | string | no | |
type | query | string | no | mod, 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
withLatestModpack | query | boolean | no | Also 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
provider | body | string | yes | provider of the search results |
projectId | body | string | yes | projectId of the search results |
versionId | body | string | yes | versionId of GET .../projects/{provider}/{projectId}/versions |
type | body | string | no | Default mod; values: mod, plugin, modpack |
projectName | body | string | no | Display name kept with the installed file |
versionName | body | string | no | Display name of the version |
gameVersion | body | string | no | |
loader | body | string | no | |
clean | body | boolean | no | Modpacks: remove the previous pack's content first |
deleteWorld | body | boolean | no | Modpacks: 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
installId | path | string | yes | installId 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
installId | path | string | yes | installId 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.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
dir | body | string | yes | values: /mods, /plugins |
fileName | body | string | yes | fileName of the installed list |
Response 200: {data: {removed}}
POST /services/{code}/games/content/installed/toggle
Permissions: games.content:write
Applies at the next start.
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
dir | body | string | yes | values: /mods, /plugins |
fileName | body | string | yes | |
enable | body | boolean | yes |
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 code | When |
|---|---|
SERVER_TRANSITIONING | the server is starting or stopping |
SETTINGS_NOT_GENERATED | the server has not created server.properties yet |
EDIT_IN_PROGRESS | another change to the server is in progress |
INSTALL_IN_PROGRESS | an install or an archive extraction is in progress |
| Parameter | In | Type | Required | Values and format |
|---|---|---|---|---|
values | body | object | no | Setting key -> value, keys from settings[].key of GET /games/settings. online-mode needs services.console:write |
icon | body | string | no | The new icon: base64 of a 64x64 PNG, 64 KiB at most |
removeIcon | body | boolean | no | Remove the icon; not with icon |
Response 200: {data: {settings, changed, restartRequired, confirmed, icon}}