Skip to content
Shardkeep

Create the network's Velocity proxy

POST
/network/proxy
curl --request POST \
  --url https://example.com/api/v1/network/proxy \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "nodeId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "version": "example", "resources": { "cpuMillis": 1, "memoryBytes": 1 } }'

Global administrators only. The proxy is a server of kind VELOCITY_PROXY, placed like any server (on nodeId when given) and published on the network’s port. Shardkeep writes its whole configuration. One per network (proxy_exists).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
nodeId

The Node to run it on; omit to let placement choose.

string format: uuid
version

A Velocity version; the newest when omitted.

string
<= 64 characters
resources

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
Examplegenerated
{
  "nodeId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "version": "example",
  "resources": {
    "cpuMillis": 1,
    "memoryBytes": 1
  }
}

Responses

Section titled “Responses”

201

Section titled “201”

The proxy, being provisioned.

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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"
}

Shardkeep is free software under the AGPL-3.0. Minecraft is a trademark of Mojang AB; Shardkeep is not affiliated with or endorsed by Mojang or Microsoft.