---
title: "Reserve GPU units on a node for a set of orgs (platform admin)"
method: POST
path: "/v1/nodes/{nodeId}/reservations"
tags: ["Reservations"]
---

# Reserve GPU units on a node for a set of orgs (platform admin)

`POST /v1/nodes/{nodeId}/reservations`

Grants exclusive placement rights over specific GPU units for a term. Reserved units disappear from every other org's catalog and cannot be placed on by them. Overlap with an existing reservation is rejected atomically.

## Path parameters

- `nodeId` string, required

## Request body

- CreateNodeReservationRequest
  - `allowedOrgIds` string[], required — The audience. The platform ops org is added automatically so we can validate the node.
  - `contractRef` string
  - `endsAt` string — Omit for open-ended
  - `reason` string
  - `startsAt` string — Defaults to now
  - `unitIds` string[], required — GPU unit ids to reserve (from the node's inventory). Must be vfio-group units.

## Response `200`

Created

- NodeReservation — Exclusive placement rights for a set of orgs over specific GPU units of one node, for a term. Scoped to units, not GPU counts, because units are the indivisible allocation primitive.
  - `allowedOrgIds` string[], required
  - `contractRef` string
  - `createdAt` string
  - `endsAt` string — Absent = open-ended until cancelled
  - `id` string, required
  - `nodeId` string, required
  - `reason` string
  - `reservedUnitIds` string[], required
  - `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.
  - `topologyGen` integer — Node topology generation this reservation was written against
  - `updatedAt` string

## Other responses

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

---

[API](https://skmtc.net/openrelay/apis/openrelay-api.md) · [All operations](https://skmtc.net/openrelay/apis/openrelay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrelay/openrelay-api/versions/4c42fd61ed41/schema)