---
title: "Set a node's operator lifecycle status (drain / maintenance / remove / online)"
method: PATCH
path: "/v1/orgs/{orgId}/provider/nodes/{nodeId}"
tags: ["Provider"]
---

# Set a node's operator lifecycle status (drain / maintenance / remove / online)

`PATCH /v1/orgs/{orgId}/provider/nodes/{nodeId}`

## Path parameters

- `orgId` string, required
- `nodeId` string, required

## Request body

- object
  - `status` 'online' | 'draining' | 'maintenance' | 'removed', required — Operator-set lifecycle state. draining/maintenance stop new placement (reconcile leaves them alone, capacity excluded); removed decommissions the node (Phase-1 reaper frees its workloads + GPU units); online clears an operator hold (the next reconcile pass re-derives true liveness from Nomad).

## Response `200`

OK

- ProviderNode
  - `cpuCores` integer, nullable
  - `cpuModel` string, nullable
  - `createdAt` string, required
  - `gpus` NodeGpuItem[], required
    - `gpuName` string, required
    - `quantity` integer, required
    - `vramGb` integer, required
  - `hostname` string, required
  - `id` string, required
  - `locationCity` string, nullable
  - `locationCountry` string, nullable
  - `nodeType` string, required
  - `ramGb` integer, nullable
  - `reservation` NodeReservationSummary — Reservation state of this node, from the caller's point of view. Present only when some of the node's GPU units are reserved.
    - `releasedUnitCount` integer, required — GPU units this node's reservations have released to the spot market. They are still the reservation's capacity: anyone may buy them, but only at tier=spot, and the capacity owner can reclaim them at any time.
    - `reservations` NodeReservation[]
      - `allowedOrgIds` string[], required — The audience: orgs that may place workloads on the reserved units.
      - `contractRef` string
      - `createdAt` string
      - `endsAt` string — Absent = open-ended until cancelled
      - `id` string, required
      - `managingOrgIds` string[] — Orgs that may release these units to the market, reclaim them, and terminate the spot workloads on them, on the node owner's behalf. Being in the audience does not confer this.
      - `nodeId` string, required
      - `reason` string
      - `releasedUnitIds` string[] — The subset of reservedUnitIds currently on the spot market (double sell). Still this reservation's capacity, sellable to anyone at tier=spot only, and reclaimable at any time.
      - `reservedUnitIds` string[], required
      - `skipped` string[] — Reclaim only: VM ids left running because they are not spot.
      - `startsAt` string, required
      - `status` 'pending' | 'active' | 'expired' | 'cancelled' | 'needs-review', required — needs-review means the node's GPU topology changed under the reservation: it grants nothing (and withholds its units from everyone) until an operator re-affirms it.
      - `terminated` string[] — Reclaim only: spot VM ids terminated to free the reclaimed units.
      - `topologyGen` integer — Node topology generation this reservation was written against
      - `updatedAt` string
      - `wouldSkip` string[] — Reclaim dry run only: VM ids that would be left running.
      - `wouldTerminate` string[] — Reclaim dry run only: the spot VM ids this call would terminate.
    - `reservedUnitCount` integer, required — GPU units held exclusively for the audience right now
  - `runtime` string — Node runtime: qemu (VFIO VM host) or runc (GPU-container Pod node). Empty reads as qemu.
  - `status` string, required
  - `tdxEnabled` boolean, required

## Other responses

- `400` — The request is invalid
- `401` — Missing or invalid API key
- `403` — API key lacks the required scope
- `404` — Resource not found

---

[API](https://skmtc.dev/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.dev/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openrelay/openrelay-api/revisions/3dc47c9667e8/schema)