Create a server
const url = 'https://example.com/api/v1/servers';const options = { method: 'POST', headers: { cookie: '__Host-shardkeep_session=<__Host-shardkeep_session>', 'Content-Type': 'application/json' }, body: '{"name":"example","teamId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","nodeId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","software":{"template":"paper","version":"1.21.4","build":"example"},"resources":{"cpuMillis":1,"memoryBytes":1},"ports":[{"name":"game","hostPort":1,"protocol":"TCP"}],"restartPolicy":{"maxRestarts":1,"windowSeconds":1},"start":false,"eulaAccepted":true,"restoreFrom":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","inNetwork":true,"initialProperties":{"additionalProperty":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/servers \ --header 'Content-Type: application/json' \ --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \ --data '{ "name": "example", "teamId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "nodeId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "software": { "template": "paper", "version": "1.21.4", "build": "example" }, "resources": { "cpuMillis": 1, "memoryBytes": 1 }, "ports": [ { "name": "game", "hostPort": 1, "protocol": "TCP" } ], "restartPolicy": { "maxRestarts": 1, "windowSeconds": 1 }, "start": false, "eulaAccepted": true, "restoreFrom": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "inNetwork": true, "initialProperties": { "additionalProperty": "example" } }'Needs servers.create over the owning team. The operator must accept the Minecraft EULA.
Without nodeId, the server is placed on the ENABLED and HEALTHY Node with the most unreserved memory that has
room for its CPU and memory reservation. Choosing a Node with nodeId needs global nodes.read; that Node must
be ENABLED (node_unavailable) and have room. No room fails with insufficient_capacity and creates nothing.
Without a game port, the first free TCP port in the Controller’s game port range (25565-25664 by default) is
assigned on the chosen Node. A requested host port already used on that Node fails with port_conflict.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
The owning team.
Place the server on this Node; needs global nodes.read. Omit to let placement choose.
What the server runs. A Shardkeep template, never a container image.
object
Example
paperExample
1.21.4A reservation, held even while the server is idle.
object
CPU in thousandths of a core.
Host ports to publish. A game port is assigned when none is given.
object
Example
gameobject
Zero disables automatic restarts.
Start the server once it is provisioned.
The operator accepts the Minecraft EULA for this server.
Create the server from this backup (needs backups.restore on its server too): it runs the backup’s software
(the given software is ignored) and gets its data before it first starts.
Make the server a network member, reached through the proxy. Defaults to true for Paper, Purpur and Folia
once the network is set up; Vanilla servers cannot be members (not_a_member_template).
Server.properties settings to start with, written before the first start: difficulty, gamemode, pvp, hardcore, view-distance, simulation-distance, max-players, motd, level-seed, white-list and spawn-protection. Change them later through the server’s properties.
object
Responses
Section titled “Responses”Server created, provisioning.
object
VELOCITY_PROXY is the network’s proxy, created with POST /network/proxy.
A network member, which players reach through the proxy (Paper, Purpur and Folia only).
Increases with every change to the desired spec.
The workflow the Controller is running.
What the server runs. A Shardkeep template, never a container image.
object
A reservation, held even while the server is idle.
object
CPU in thousandths of a core.
object
object
Zero disables automatic restarts.
Observed state, written only from Agent reports.
object
Absent until the Agent first reports.
object
CPU in thousandths of a core.
Why observed state differs from desired state, or why a Node is under pressure.
object
Machine-readable cause, such as DISK_PRESSURE. New reasons may appear; treat unknown ones as unrecognised conditions.
How observed state relates to desired state. UNKNOWN while the Node is unreachable.
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"}The request is invalid.
An RFC 9457 problem with a machine-readable code.
object
Stable machine-readable error code.
Example
{ "type": "about:blank", "title": "Conflict", "status": 409, "code": "conflict"}Not signed in, or the credentials are invalid.
An RFC 9457 problem with a machine-readable code.
object
Stable machine-readable error code.
Example
{ "type": "about:blank", "title": "Conflict", "status": 409, "code": "conflict"}Signed in, but not allowed.
An RFC 9457 problem with a machine-readable code.
object
Stable machine-readable error code.
Example
{ "type": "about:blank", "title": "Conflict", "status": 409, "code": "conflict"}Clashes with existing data or state.
An RFC 9457 problem with a machine-readable code.
object
Stable machine-readable error code.
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.