Skip to content
Shardkeep

Add a Node

POST
/nodes
curl --request POST \
  --url https://example.com/api/v1/nodes \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "name": "example" }'

The Node starts ENABLED and AWAITING_ENROLLMENT. Enrollment tokens arrive with Node security (Phase 5).

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
>= 1 characters <= 64 characters /^[A-Za-z0-9][A-Za-z0-9._-]*$/
Examplegenerated
{
  "name": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Node added, awaiting enrollment.

Media typeapplication/json
object
id
required
string format: uuid
name
required
string
adminState
required

Set by administrators (desired state).

string
Allowed values: ENABLED DISABLED REVOKED
acceptsPlacements
required

True only when ENABLED and HEALTHY.

boolean
address

Where other Nodes reach this Node’s published ports (the proxy reaching members), as an administrator set it; empty to use status.observedAddress.

string
reachAddress

The address in use, address or else status.observedAddress; empty while unknown.

string
createdAt
required
string format: date-time
status
required

What the Controller observes about the Node.

object
observedAddress

The IP address the Node’s Agent last connected from.

string
connectionState
required
string
Allowed values: AWAITING_ENROLLMENT HEALTHY DEGRADED UNREACHABLE
agentVersion
required
string
hostname
required
string
os
required
string
arch
required
string
runtimeName
required
string
runtimeVersion
required
string
allocatable
required
object
cpuMillis
required

CPU in thousandths of a core.

integer format: int64
memoryBytes
required
integer format: int64
diskBytes
required
integer format: int64
usage
required
object
cpuMillis
required

CPU in thousandths of a core.

integer format: int64
memoryBytes
required
integer format: int64
diskBytes
required
integer format: int64
lastHeartbeatAt
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
reserved
required

CPU and memory reserved by the servers on the Node, stopped ones included.

object
cpuMillis
required

CPU in thousandths of a core.

integer format: int64
memoryBytes
required
integer format: int64
free
required

Allocatable minus reserved; what new servers can still reserve.

object
cpuMillis
required

CPU in thousandths of a core.

integer format: int64
memoryBytes
required
integer format: int64
Example
{
  "adminState": "ENABLED",
  "status": {
    "connectionState": "AWAITING_ENROLLMENT"
  },
  "conditions": [
    {
      "source": "AGENT"
    }
  ]
}

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

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.