Client API: Deployment servers: Software

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Every addon in the folders the server loads from, tracked or hand-uploaded

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Every addon in the folders the server loads from, tracked or hand-uploaded

GET /api/v1/client/servers/{uuid}/software/addons

Every addon in the folders the server loads from, tracked or hand-uploaded.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`kind`	query	string or null	no	plugin, mod or datapack; omit for every kind

Responses

Section titled Drop a tracking record whose files are gone, without touching the disk

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Drop a tracking record whose files are gone, without touching the disk

DELETE /api/v1/client/servers/{uuid}/software/addons/records/{record_uuid}

Drop a tracking record whose files are gone, without touching the disk.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`record_uuid`	path	string	yes

Responses

Section titled Delete one addon from disk, through the tracked uninstall when it has a record

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete one addon from disk, through the tracked uninstall when it has a record

POST /api/v1/client/servers/{uuid}/software/addons/remove

Delete one addon from disk, through the tracked uninstall when it has a record.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Switch one addon file on or off (Foo.jar <- Foo.jar.disabled)

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Switch one addon file on or off (Foo.jar <- Foo.jar.disabled)

POST /api/v1/client/servers/{uuid}/software/addons/toggle

Switch one addon file on or off (Foo.jar <-> Foo.jar.disabled).

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Turn Bedrock crossplay on or off for a Java server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Turn Bedrock crossplay on or off for a Java server

POST /api/v1/client/servers/{uuid}/software/bedrock

Turn Bedrock crossplay on or off for a Java server.

Crossplay lets players on Minecraft Bedrock join your Java server, through Geyser and Floodgate. Send {"enabled": true} to turn it on: both plugins are installed before this answers, Geyser gets a port of its own, and the server loads the plugins when it next starts. Send {"enabled": false} to turn it off: both plugins and their folders are deleted and Geyser's port goes back to the pool. A body without enabled turns crossplay off. The answer is the crossplay state.

It answers 400 with the reason, and nothing changes, when the server cannot run Geyser (it runs mods, Vanilla, a proxy or a Bedrock server, or a Java older than 21), when GeyserMC's downloads do not answer, or when a plugin cannot be installed on the server. A enabled that is not true or false answers 422. On a server shared with you, it needs software.install. Each request is recorded in the server's activity log.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`enabled`	boolean	no	`true` turns Bedrock crossplay on: Geyser and Floodgate are installed before the request answers. `false` turns it off and removes both. A body without `enabled` turns crossplay off.

Responses

Section titled Choose where Bedrock crossplay takes Geyser from: release or development

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Choose where Bedrock crossplay takes Geyser from: release or development

PUT /api/v1/client/servers/{uuid}/software/bedrock/channel

Choose where Bedrock crossplay takes Geyser from: release or development.

release, the default, is GeyserMC's newest release. development is the newest build of GeyserMC's GitHub build workflow: while GeyserMC works on a new Minecraft version in a branch named after it, the newest build of that branch, and otherwise the newest build of master. Choose it when the server runs a Minecraft version that no Geyser release supports yet. Floodgate always comes from its release.

With crossplay on, the chosen Geyser is installed before this answers, and each start after that updates it from the same place; restart the server to load it. With crossplay off, the choice applies when crossplay is turned on, and turning crossplay off sets it back to release. The answer is the crossplay state, with geyser_channel. When the builds cannot be downloaded it answers 400 with the reason and nothing changes. On a server shared with you, it needs software.install.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`channel`	string, one of `release`, `development`	yes	Where Bedrock crossplay takes Geyser from. `release` is GeyserMC's newest release, the default. `development` is the newest build of GeyserMC's GitHub build workflow, which supports a new Minecraft version before a release does and has had less testing.

Responses

Section titled Behavior and resource packs on disk, which are active in the world, and importable uploads

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Behavior and resource packs on disk, which are active in the world, and importable uploads

GET /api/v1/client/servers/{uuid}/software/bedrock/packs

Behavior and resource packs on disk, which are active in the world, and importable uploads.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Empty the world's activation lists so it boots on vanilla content; folders stay

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Empty the world's activation lists so it boots on vanilla content; folders stay

POST /api/v1/client/servers/{uuid}/software/bedrock/packs/disable-all

Empty the world's activation lists so it boots on vanilla content; folders stay.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server

POST /api/v1/client/servers/{uuid}/software/bedrock/packs/import

Queue an import of an uploaded .mcaddon / .mcpack / .zip already on the server.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Add a pack to, or drop it from, the world's activation list

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Add a pack to, or drop it from, the world's activation list

POST /api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/active

Add a pack to, or drop it from, the world's activation list.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`pack_uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Deactivate a pack, delete its folder, and drop its tracking row

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Deactivate a pack, delete its folder, and drop its tracking row

POST /api/v1/client/servers/{uuid}/software/bedrock/packs/{pack_uuid}/remove

Deactivate a pack, delete its folder, and drop its tracking row.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`pack_uuid`	path	string	yes

Responses

Section titled Texturepack-required: players must accept the resource packs to join

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Texturepack-required: players must accept the resource packs to join

PUT /api/v1/client/servers/{uuid}/software/bedrock/texturepack-required

texturepack-required: players must accept the resource packs to join.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Server software the machine can be switched to, grouped for display

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Server software the machine can be switched to, grouped for display

GET /api/v1/client/servers/{uuid}/software/catalog

Server software the machine can be switched to, grouped for display.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Installable versions for one catalog entry, with runtime recommendations

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Installable versions for one catalog entry, with runtime recommendations

GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions

Installable versions for one catalog entry, with runtime recommendations.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`key`	path	string	yes
`limit`	query	integer	no	Default: `200`.
`include_unsupported`	query	boolean	no	Default: `False`.

Responses

Section titled Publisher builds of one game version: the loader versions for Fabric/Forge

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Publisher builds of one game version: the loader versions for Fabric/Forge

GET /api/v1/client/servers/{uuid}/software/catalog/{key}/versions/{version}/builds

Publisher builds of one game version: the loader versions for Fabric/Forge.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`key`	path	string	yes
`version`	path	string	yes

Responses

Section titled Switch the server to different software, or a different version of it

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Switch the server to different software, or a different version of it

POST /api/v1/client/servers/{uuid}/software/change

Switch the server to different software, or a different version of it.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Return loader/game-version context for marketplace tab gating

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Return loader/game-version context for marketplace tab gating

GET /api/v1/client/servers/{uuid}/software/context

Return loader/game-version context for marketplace tab gating.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled What a version requires, named, with what is already installed marked

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

What a version requires, named, with what is already installed marked

GET /api/v1/client/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}

What a version requires, named, with what is already installed marked.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`source_uuid`	path	string	yes
`identifier`	path	string	yes
`version`	query	string	no	The version whose dependencies to resolve; latest resolves as the installer would Default: `latest`.
`kind`	query	string or null	no

Responses

Section titled The server's game settings in server.properties words, whatever file holds them

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The server's game settings in server.properties words, whatever file holds them

GET /api/v1/client/servers/{uuid}/software/game-settings

The server's game settings in server.properties words, whatever file holds them.

format is server.properties (every key the file has, in values) or pumpkin.toml (Pumpkin: the keys settings lists, each with its kind and limits, plus bedrock-players). exists is false before the game first wrote its file. Changes apply on the next start. Needs file.read-content.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Change game settings: {"values": {"difficulty": "hard", "max-players": 20}}

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change game settings: {"values": {"difficulty": "hard", "max-players": 20}}

PATCH /api/v1/client/servers/{uuid}/software/game-settings

Change game settings: {"values": {"difficulty": "hard", "max-players": 20}}.

Keys are server.properties words; null puts a key back to its default. On a Pumpkin server only the keys GET lists are taken, each checked the way Pumpkin reads it, and an unknown key or a value out of range answers 400 naming what it takes. At most 40 keys at once. Needs file.update. Recorded in the server's activity log.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Queue a software install job

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Queue a software install job

POST /api/v1/client/servers/{uuid}/software/install

Queue a software install job.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`source_uuid`	query	string or null	no
`identifier`	query	string or null	no
`software_id`	query	string or null	no
`version`	query	string or null	no
`kind`	query	string or null	no

Request body

application/json

Type: object or null.

Responses

Section titled List recent software install jobs for a server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

List recent software install jobs for a server

GET /api/v1/client/servers/{uuid}/software/installs

List recent software install jobs for a server.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`status`	query	string or null	no

Responses

Section titled Get a single software install job

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get a single software install job

GET /api/v1/client/servers/{uuid}/software/installs/{install_uuid}

Get a single software install job.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`install_uuid`	path	string	yes

Responses

Section titled Cancel a queued software install

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Cancel a queued software install

POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/cancel

Cancel a queued software install.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`install_uuid`	path	string	yes

Responses

Section titled Queue a fresh install job with the same parameters as a failed one

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Queue a fresh install job with the same parameters as a failed one

POST /api/v1/client/servers/{uuid}/software/installs/{install_uuid}/retry

Queue a fresh install job with the same parameters as a failed one.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`install_uuid`	path	string	yes

Responses

Section titled The heap slider and the allowlisted startup flags, as the panel shows them

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The heap slider and the allowlisted startup flags, as the panel shows them

GET /api/v1/client/servers/{uuid}/software/jvm

The heap slider and the allowlisted startup flags, as the panel shows them.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Move the heap, pick startup flags from the catalog, or reset both

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Move the heap, pick startup flags from the catalog, or reset both

PATCH /api/v1/client/servers/{uuid}/software/jvm

Move the heap, pick startup flags from the catalog, or reset both. Applies on restart.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled The server resource pack as server.properties declares it

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The server resource pack as server.properties declares it

GET /api/v1/client/servers/{uuid}/software/resource-pack

The server resource pack as server.properties declares it.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Point players at a pack, from a URL or a marketplace resource pack version

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Point players at a pack, from a URL or a marketplace resource pack version

PUT /api/v1/client/servers/{uuid}/software/resource-pack

Point players at a pack, from a URL or a marketplace resource pack version.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Stop offering a server resource pack

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Stop offering a server resource pack

DELETE /api/v1/client/servers/{uuid}/software/resource-pack

Stop offering a server resource pack.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now

POST /api/v1/client/servers/{uuid}/software/safe-mode

Arm a one-shot --safeMode start (vanilla datapack only), optionally starting now.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

application/json (required)

Type: Body.

Responses

Section titled Search available software (JSON body preferred; query params kept for back-compat)

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Search available software (JSON body preferred; query params kept for back-compat)

POST /api/v1/client/servers/{uuid}/software/search

Search available software (JSON body preferred; query params kept for back-compat).

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`query`	query	string or null	no
`page`	query	integer	no	Default: `1`.
`limit`	query	integer	no	Default: `20`.
`source_uuid`	query	string or null	no
`kind`	query	string or null	no
`sort`	query	string or null	no

Request body

application/json

Type: object or null.

Responses

Section titled List enabled software sources for a kind

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

List enabled software sources for a kind

GET /api/v1/client/servers/{uuid}/software/sources

List enabled software sources for a kind.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes
`kind`	query	string or null	no

Responses

Section titled Newer compatible builds for the addons the marketplace installed

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Newer compatible builds for the addons the marketplace installed

GET /api/v1/client/servers/{uuid}/software/updates

Newer compatible builds for the addons the marketplace installed.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`kind`	query	string or null	no
`include_current`	query	boolean	no	Also return addons already on the newest build Default: `False`.

Responses

Section titled Get available versions for software

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get available versions for software

GET /api/v1/client/servers/{uuid}/software/versions/{source_uuid}/{identifier}

Get available versions for software.

Plugin and mod lookups default to builds that fit this server's loader and game version; each row carries compatible and incompatible_reason.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`source_uuid`	path	string	yes
`identifier`	path	string	yes
`page`	query	integer	no	Default: `1`.
`limit`	query	integer	no	Default: `50`.
`loaders`	query	string or null	no	Comma-separated loaders
`game_versions`	query	string or null	no	Comma-separated game versions
`kind`	query	string or null	no	Content kind; datapacks ignore the server loader
`include_incompatible`	query	boolean	no	List builds for other loaders / game versions too, flagged Default: `False`.

Responses

Section titled Turn ViaVersion and ViaBackwards on or off for a Minecraft Java server

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Turn ViaVersion and ViaBackwards on or off for a Minecraft Java server

POST /api/v1/client/servers/{uuid}/software/via

Turn ViaVersion and ViaBackwards on or off for a Minecraft Java server.

ViaVersion lets players on newer Minecraft versions join the server, and ViaBackwards lets players on older versions join. Every Paper, Purpur, Folia or Spigot server has both unless you turn them off: we install them in the server's plugins folder and update them each time it starts.

{"enabled": true} installs the newest releases before it answers; restart the server to load them. {"enabled": false} removes plugins/ViaVersion.jar and plugins/ViaBackwards.jar and keeps them off. Their settings folders stay. A copy you added yourself under its own name, such as ViaVersion-5.12.0.jar, is never touched, and while it is there we do not install ours.

The answer is the state software/context shows under via_plugins. It answers 400 with the reason, and changes nothing, when the server cannot load these plugins, when the releases cannot be downloaded or when the server's files cannot be reached. On a server shared with you, it needs software.install.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body