Register node

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

string

required

Must be "caravanserai/v1".

string

required

Must be "Node".

object

required

Show properties

string

required

Unique name of the node within the cluster. Must be a valid DNS label (lowercase alphanumeric and hyphens, no leading/trailing hyphens).

object

Arbitrary key/value string pairs for selection and grouping.

object

Non-identifying key/value metadata.

object

Show properties

string

OS-level hostname of the machine.

boolean

default:"false"

When true, the scheduler will not assign new projects to this node. Defaults to false.

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
    }
  }'

{
  "apiVersion": "caravanserai/v1",
  "kind": "Node",
  "metadata": {
    "name": "worker-01",
    "labels": {
      "zone": "hsinchu"
    },
    "createdAt": "2025-04-06T12:00:00Z",
    "updatedAt": "2025-04-06T12:00:00Z"
  },
  "spec": {
    "hostname": "worker-01.local",
    "unschedulable": false
  },
  "status": {
    "state": "NotReady"
  }
}

{
  "title": "Conflict",
  "detail": "node already exists: worker-01",
  "status": 409,
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409"
}

Overview

Nodes

Projects

Request body

Response

Example

​Request body

​Response

​Example

Request body

Response

Example