Change a server's Minecraft version or build

PUT

/servers/{serverId}/software

curl --request PUT \
  --url https://example.com/api/v1/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/software \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "version": "1.21.4", "build": "example", "force": false }'

Needs servers.update; audited. Moves a READY server to another version or build of the same software (an absent build means the newest). The server is UPDATING while the Controller obtains and verifies the new software, then READY again; a running server takes it on when it next starts. If the software cannot be obtained, the server keeps its current software and gets a software-change condition saying why.

Minecraft worlds cannot be safely downgraded, so a lower version is refused (software_downgrade). Installed catalog plugins not marked for the new version are listed in a plugins_incompatible refusal unless force is set; uploaded plugins are not checked.

Authorizations

• sessionCookie
• bearerToken

Parameters

Path Parameters

serverId

required

string format: uuid

Request Body^required

Media typeapplication/json

object

version

required

string

>= 1 characters <= 32 characters

Example

1.21.4

build

The newest build when absent.

string

<= 32 characters

force

Change even if installed plugins are not marked for the new version.

boolean

Responses

202

Accepted; the server is UPDATING.

Media typeapplication/json

object

id

required

string format: uuid

name

required

string

teamId

required

string format: uuid

nodeId

string format: uuid

kind

required

VELOCITY_PROXY is the network’s proxy, created with POST /network/proxy.

string

Allowed values: MINECRAFT_SERVER VELOCITY_PROXY

inNetwork

required

A network member, which players reach through the proxy (Paper, Purpur and Folia only).

boolean

desiredState

required

string

Allowed values: RUNNING STOPPED DELETED

generation

required

Increases with every change to the desired spec.

integer format: int64

phase

required

The workflow the Controller is running.

string

Allowed values: PROVISIONING READY MIGRATING RESTORING UPDATING DELETING FAILED

software

required

What the server runs. A Shardkeep template, never a container image.

object

template

required

string

>= 1 characters <= 64 characters /^[a-z0-9][a-z0-9-]*$/

version

required

string

>= 1 characters <= 64 characters

build

string

<= 64 characters

resources

required

A reservation, held even while the server is idle.

object

cpuMillis

required

CPU in thousandths of a core.

integer format: int64

>= 1

memoryBytes

required

integer format: int64

>= 1

ports

required

Array<object>

object

name

required

string

>= 1 characters <= 32 characters

hostPort

required

integer

>= 1 <= 65535

protocol

required

string

Allowed values: TCP UDP

restartPolicy

required

object

maxRestarts

required

Zero disables automatic restarts.

integer

<= 100

windowSeconds

required

integer

>= 1 <= 86400

acknowledgedConditionIds

required

Array<string>

eulaAcceptedAt

string format: date-time

createdAt

required

string format: date-time

status

required

Observed state, written only from Agent reports.

object

runtimeState

Absent until the Agent first reports.

string

Allowed values: STOPPED STARTING RUNNING STOPPING CRASHED

appliedGeneration

required

integer format: int64

removed

required

boolean

usage

required

object

cpuMillis

required

CPU in thousandths of a core.

integer format: int64

memoryBytes

required

integer format: int64

diskBytes

required

integer format: int64

observedAt

string format: date-time

conditions

required

Array<object>

Why observed state differs from desired state, or why a Node is under pressure.

object

id

required

string

source

required

string

Allowed values: AGENT CONTROLLER

reason

required

Machine-readable cause, such as DISK_PRESSURE. New reasons may appear; treat unknown ones as unrecognised conditions.

string

message

required

string

since

required

string format: date-time

convergence

required

How observed state relates to desired state. UNKNOWN while the Node is unreachable.

string

Allowed values: CONVERGED IN_PROGRESS DISCREPANCY UNKNOWN

Example

{
  "kind": "MINECRAFT_SERVER",
  "desiredState": "RUNNING",
  "phase": "PROVISIONING",
  "software": {
    "template": "paper",
    "version": "1.21.4"
  },
  "ports": [
    {
      "name": "game",
      "protocol": "TCP"
    }
  ],
  "status": {
    "runtimeState": "STOPPED",
    "conditions": [
      {
        "source": "AGENT"
      }
    ]
  },
  "convergence": "CONVERGED"
}

400

The request is invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

401

Not signed in, or the credentials are invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

403

Signed in, but not allowed.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

404

Not found, or not visible to you.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

409

Clashes with existing data or state.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object

type

required

string

title

required

string

status

required

integer

detail

string

code

required

Stable machine-readable error code.

string

Example

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}