Skip to main content
All endpoints require HTTP Basic Auth. See REST API overview for authentication and configuration details.

​
GET /api/nodes/

Get all nodes, including field values inherited from associated profiles. 
curl -u admin:admin http://localhost:9873/api/nodes/
Response — a JSON object mapping node IDs to node objects: 
{
  "n01": {
    "profiles": ["default"],
    "image name": "rockylinux-9",
    "system overlay": ["wwinit", "wwclient"],
    "runtime overlay": ["hosts", "ssh.authorized_keys"]
  },
  "n02": {
    "profiles": ["default"],
    "image name": "rockylinux-9"
  }
}

​
GET /api/nodes/{id}

Get a single node by its ID, including field values from associated profiles.
​
id
string
required
The node ID (hostname).
curl -u admin:admin http://localhost:9873/api/nodes/n01
Response — the node object for the requested ID.

​
GET /api/nodes/{id}/raw

Get a node by its ID without resolving field values from associated profiles. Returns only fields explicitly set on the node itself.
​
id
string
required
The node ID (hostname).
curl -u admin:admin http://localhost:9873/api/nodes/n01/raw
Response — the raw node object, with no profile inheritance applied.

​
GET /api/nodes/{id}/fields

Get the fields and values for a node, showing which profile each field originates from.
​
id
string
required
The node ID (hostname).
curl -u admin:admin http://localhost:9873/api/nodes/n01/fields
Response — an array of field objects: 
[
  {
    "field": "Image",
    "value": "rockylinux-9",
    "source": "default"
  },
  {
    "field": "SystemOverlay",
    "value": "wwinit",
    "source": "n01"
  }
]

​
PUT /api/nodes/{id}

Add a new node. The request body provides the initial field values for the node.
​
id
string
required
The ID (hostname) to assign to the new node.
Request body:
​
node
object
required
The node configuration. All fields are optional.
To ensure a node is only created if it does not already exist, pass the If-None-Match: * header. 
curl -u admin:admin \
  -X PUT \
  -H "Content-Type: application/json" \
  -H "If-None-Match: *" \
  -d '{"node": {"profiles": ["default"], "image name": "rockylinux-9"}}' \
  http://localhost:9873/api/nodes/n01
Response — the created node object.

​
PATCH /api/nodes/{id}

Update an existing node. Fields provided in the request body are merged into the existing node configuration.
​
id
string
required
The node ID (hostname) of the node to update.
Request body:
​
node
object
required
The fields to update on the node. Only provided fields are changed.
curl -u admin:admin \
  -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"node": {"image name": "rockylinux-9-new"}}' \
  http://localhost:9873/api/nodes/n01
Response — the updated node object.

​
DELETE /api/nodes/{id}

Delete an existing node.
​
id
string
required
The node ID (hostname) of the node to delete.
curl -u admin:admin \
  -X DELETE \
  http://localhost:9873/api/nodes/n01
Response — the deleted node object.

​
POST /api/nodes/overlays/build

Build system and runtime overlay images for all nodes. 
curl -u admin:admin \
  -X POST \
  http://localhost:9873/api/nodes/overlays/build
Response — an array of node IDs for which overlays were built: 
["n01", "n02", "n03"]

​
POST /api/nodes/{id}/overlays/build

Build system and runtime overlay images for a specific node.
​
id
string
required
The node ID (hostname) of the node to build overlays for.
curl -u admin:admin \
  -X POST \
  http://localhost:9873/api/nodes/n01/overlays/build
Response — the node ID as a string: 
"n01"

Build docs developers (and LLMs) love

Get started for freeTalk to us