Skip to content
Shardkeep

List Nodes

GET
/nodes
curl --request GET \
  --url https://example.com/api/v1/nodes \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session>

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
>= 1 <= 200

At most this many items (default 50).

cursor
string
<= 200 characters

The nextCursor of the previous page.

Responses

Section titled “Responses”

200

Section titled “200”

Nodes in creation order.

Media typeapplication/json
object
items
required
Array<object>
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
nextCursor
string
Example
{
  "items": [
    {
      "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"
}

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.