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