Skip to main content
Registers a new node with the control plane. 
POST /api/v1/nodes
cara-agent calls this endpoint automatically on startup. You only need to call it directly if you are registering a node manually or building a custom agent.

​
Request body

​
apiVersion
string
required
Must be "caravanserai/v1".
​
kind
string
required
Must be "Node".
​
metadata
object
required
​
spec
object

​
Response

Returns 201 Created with the registered Node object. The server initialises status.state to NotReady; the agent transitions it to Ready once heartbeats are confirmed.

​
Example

curl -X POST http://localhost:8080/api/v1/nodes \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "caravanserai/v1",
    "kind": "Node",
    "metadata": {
      "name": "worker-01",
      "labels": {
        "zone": "hsinchu"
      }
    },
    "spec": {
      "hostname": "worker-01.local",
      "unschedulable": false
    }
  }'