GET /api/v1/nodes/{name}
Path parameters
string
required
The unique name of the node.
Response
Returns aNode object.
string
required
Always
"caravanserai/v1".string
required
Always
"Node".object
required
Show properties
Show properties
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.
Examples
curl http://localhost:8080/api/v1/nodes/worker-01
{
"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"
}
]
}
}
{
"title": "Not Found",
"detail": "node not found: worker-01",
"status": 404,
"type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404"
}