Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
Skip to Content
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceProvidersProvider

Set a node's lifecycle status

Sets the lifecycle status of a node your organization owns to one of online, draining, maintenance, or removed, and returns the node as updated. draining and removed also terminate the VMs and pods on the node that are not already stopped; removed ends stopped pods too. A removed node answers 400 NODE_DECOMMISSIONED; re-enroll it to bring it back.

Required permission

Requires the provider.write permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl provider node update <node-id> --status <status>
PATCH
/v1/orgs/{orgId}/provider/nodes/{nodeId}

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Path Parameters

orgId*string
nodeId*string

Request Body

application/json
  1. body
status*string

Operator-set lifecycle state. draining and maintenance stop new placement; draining also terminates the node's workloads, while maintenance leaves them running. removed decommissions the node (its workloads and GPU units are freed); online clears an operator hold, and the next reconcile may set it back to offline if Nomad reports it down.

Value in"online""draining""maintenance""removed"

Response Body

OK

application/json
  1. response
id*string
hostname*string
nodeType*string
runtime?string

Node runtime, which is the product this node serves: qemu (VFIO VM host), runc (GPU-container Pod node) or process (an interruptible container). Empty reads as qemu. The runtime is detected on the box at enroll (bare metal becomes qemu, a virtualised guest becomes runc) and is never chosen on the provisioning token, so read it here after install to confirm the detection; see https://docs.openrelay.inc/docs/providers.

noticeSeconds?integer

Interruptible nodes only: the notice applied to a termination notice that names no deadline.

terminateAt?string

When the node is removed: on an interruptible node, set by a termination notice or offboard; on a persistent node, set by a decommission with notice, until which its rentals keep running and it takes no new ones. null when none is scheduled.

tdxEnabled*boolean
status*string
cpuModel?string
cpuCores?integer
ramGb?integer
diskFreeGb?integer

Free GB on the node's VM/pod data directory, from its last heartbeat. null when the node has no live tunnel: unknown, not zero free.

diskTotalGb?integer

Total GB of the node's VM/pod data directory, from its last heartbeat. null when the node has no live tunnel: unknown, not zero capacity.

createdAt*string
locationCity?string
locationCountry?string
gpus*array<>
reservation?

Reservation state of this node, from the caller's point of view. Present only when some of the node's GPU units are reserved.

Example Request
curl -X PATCH 'https://api.openrelay.inc/v1/orgs/string/provider/nodes/string' \  -H 'Content-Type: application/json' \  -d '{  "status": "online"}'
Example Response
{  "id": "string",  "hostname": "string",  "nodeType": "string",  "runtime": "string",  "noticeSeconds": 0,  "terminateAt": "string",  "tdxEnabled": true,  "status": "string",  "cpuModel": "string",  "cpuCores": 0,  "ramGb": 0,  "diskFreeGb": 0,  "diskTotalGb": 0,  "createdAt": "string",  "locationCity": "string",  "locationCountry": "string",  "gpus": [    {      "gpuName": "string",      "vramGb": 0,      "quantity": 0    }  ],  "reservation": {    "reservedUnitCount": 0,    "releasedUnitCount": 0,    "reservations": [      {        "id": "string",        "nodeId": "string",        "reservedUnitIds": [          "string"        ],        "releasedUnitIds": [          "string"        ],        "allowedOrgIds": [          "string"        ],        "managingOrgIds": [          "string"        ],        "startsAt": "string",        "endsAt": "string",        "status": "pending",        "topologyGen": 0,        "contractRef": "string",        "reason": "string",        "createdAt": "string",        "updatedAt": "string",        "terminated": [          "string"        ],        "skipped": [          "string"        ],        "wouldTerminate": [          "string"        ],        "wouldSkip": [          "string"        ]      }    ]  }}

List provider nodes with GPUs and location GET

Returns the organization's nodes, newest first, with hardware, GPUs, location and status. Removed nodes are left out unless includeRemoved is set. A status filter returns only the nodes in that status, removed included. Each node also carries its disk space while its tunnel is up, and a summary of any live reservation on it.

Offboard an interruptible node POST

Moves an interruptible node to draining at once and removes it at the deadline: terminateAt, or now plus noticeSeconds, or now when neither is given (send {}). A deadline only ever moves earlier, so repeating or replaying the call is safe. Use it to pass on a reclaim warning from the market the container runs in, or to take a node out yourself. Persistent nodes are offboarded with `orl provider node update --status removed`.