GET /api/v1/nodes
Query parameters
This endpoint has no query parameters.Response
Returns aNodeList object.
string
required
Always
"caravanserai/v1".string
required
Always
"NodeList".object[]
required
Array of Node objects. Empty when no nodes are registered.
Show items[]
Show items[]
string
Always
"caravanserai/v1".string
Always
"Node".object
Show properties
Show properties
string
required
Unique name of the node within the cluster.
object
Arbitrary key/value string pairs used for selection and grouping.
object
Non-identifying key/value metadata (e.g. human-readable hints).
string
RFC 3339 timestamp set by the server on first write.
string
RFC 3339 timestamp updated by the server on every write.
object
object
Runtime state reported by the agent and computed by the controller manager.
Show properties
Show properties
string
High-level health summary. One of
Ready, NotReady, or Draining.string
RFC 3339 timestamp of the most recent heartbeat received from the agent.
object
Overlay-network connectivity details.
Show properties
Show properties
string
Headscale-assigned overlay IP address (e.g.
"100.64.0.5").string
MagicDNS FQDN for service discovery.
string
Connectivity mode:
Direct (peer-to-peer path) or DERP (relayed).integer
TCP port the agent’s HTTP server listens on.
object
Raw physical resource totals reported by the agent (e.g.
{"cpu": "4000m", "memory": "8Gi"}).object
Capacity minus system-reserved amounts. The scheduler uses this to compute available headroom.
object[]
List of observable node conditions.
Show conditions[]
Show conditions[]
string
required
Machine-readable identifier, e.g.
"Ready".string
required
One of
True, False, or Unknown.string
CamelCase word summarising why the condition has this status.
string
Human-readable explanation.
string
RFC 3339 timestamp of when this condition was last sampled.
string
RFC 3339 timestamp of when the status last changed.
Example
curl http://localhost:8080/api/v1/nodes
{
"apiVersion": "caravanserai/v1",
"kind": "NodeList",
"items": [
{
"apiVersion": "caravanserai/v1",
"kind": "Node",
"metadata": {
"name": "worker-01",
"labels": {
"zone": "hsinchu"
},
"createdAt": "2025-04-01T08:00:00Z",
"updatedAt": "2025-04-06T12:34:56Z"
},
"spec": {
"hostname": "worker-01.local",
"unschedulable": false
},
"status": {
"state": "Ready",
"lastHeartbeat": "2025-04-06T12:34:56Z",
"network": {
"ip": "100.64.0.5",
"dnsName": "worker-01.cluster.local",
"mode": "Direct",
"agentPort": 9090
},
"capacity": {
"cpu": "4000m",
"memory": "8Gi"
},
"allocatable": {
"cpu": "3800m",
"memory": "7Gi"
},
"conditions": [
{
"type": "Ready",
"status": "True",
"reason": "AgentReady",
"message": "Heartbeat received within threshold",
"lastHeartbeatTime": "2025-04-06T12:34:56Z",
"lastTransitionTime": "2025-04-01T08:00:00Z"
}
]
}
}
]
}