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

Offboard an interruptible node

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`.

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 offboard <node-id>
POST
/v1/orgs/{orgId}/provider/nodes/{nodeId}/offboard

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

A termination notice: name the deadline with terminateAt or noticeSeconds, not both. Neither means now on offboard. A node's own notice (POST /v1/nodes/termination-notice) takes the same body: from an interruptible node, neither means the token's noticeSeconds; from a persistent node it is a leave notice, accepted when its organization has leave notices enabled, and it must name a deadline 5 minutes to 7 days ahead.

noticeSeconds?integer

Remove the node this many seconds from now (at most 24 h for an interruptible node).

Range0 <= value <= 86400
terminateAt?string

Remove the node at this time (RFC 3339; for an interruptible node at most 24 h ahead, and a past time means now).

Formatdate-time

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 notice to go offline, 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 POST 'https://api.openrelay.inc/v1/orgs/string/provider/nodes/string/offboard' \  -H 'Content-Type: application/json' \  -d '{}'
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"        ]      }    ]  }}

Set a node's lifecycle status PATCH

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.

Provider node + token stats GET

Returns counts of the organization's nodes (total, online and offline, removed nodes excluded) and of its provisioning tokens that can still enroll a node.