Node API

Lists fleet nodes within the permitted region scope.

Requires fleet:read. Filters include region_id, zone_id, pool_id, health, cordoned, and label, plus standard pagination. cordoned accepts only true or false.

Returns the configuration ETag and observed host state. The response separates capacity.physical, capacity.allocatable, capacity.reserved, and usage; clients must not infer free admission capacity by subtracting recent usage from physical memory.

A node response identifies its placement, admission state, and observation time:

{
  "data": {
    "id": "nod_eu01",
    "revision": 8,
    "region_id": "reg_euwest",
    "zone_id": "zone_a",
    "pool_id": "pool_general",
    "cordoned": true,
    "roles": ["compute", "storage"],
    "cpu_profile_ids": ["cpu_baseline_v2"],
    "observed_at": "2025-11-23T11:30:00Z"
  }
}

Absent observations remain absent rather than becoming zero-valued capacity. A last-observed node ID remains stable through service restarts.

Updates node admission, labels, taints, or eligible location fields.

Requires If-Match. Writable fields are cordoned, cordon_reason, labels, taints, zone_id, rack, and supported admission limits. Omission preserves a field; labels replaces the full map. Cordoning blocks new destinations without stopping existing guests.

Changing location fields while placement dependencies exist returns 409 node_location_in_use. Use the reviewed evacuation workflow before changing a zone or rack. The destination zone must remain in the node's region. Unsupported admission limits return 422.

Previews drain destinations and blockers without changing placement.

Accepts an optional destination_pool_id and returns eligible moves and blockers without changing placement. The result records source revisions but does not reserve destinations indefinitely.

Starts a reviewed node drain and cordons the source.

Send type=drain and the preview ID with If-Match. The request returns 202 with a parent operation. The node becomes cordoned. Successful child migrations remain applied when another child fails.

Compute drain does not evacuate replicas. Inspect storage pool evacuation for nodes with a storage role.

Retires an evacuated node and revokes its identity.

Use the action type=retire only after compute and storage dependencies are clear. It revokes the node identity and returns an operation reference. An occupied host returns 409 node_in_use; an unresolved writer returns 409 fencing_required.

Retirement does not wipe local disks. Use the organization's hardware sanitation procedure before disposing of the host. See node fencing, CPU profiles, and enrollment tokens.