Stop a server

POST

/servers/{serverId}/stop

curl --request POST \
  --url https://example.com/api/v1/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/stop \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session>

Needs servers.stop. Changes desired state only; the Agent applies it later, so the response is 202 with the new generation. Refused with phase_busy while another workflow runs for the server.

Authorizations

• sessionCookie
• bearerToken

Parameters

Path Parameters

serverId

required

string format: uuid

Responses

202

Stop requested.

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"
}

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"
}