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

Reserve GPU units for orgs (platform admin)

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.

Required permission

Requires the reservation.manage permission. A caller without it gets 404. See Permissions for the roles and API key permissions that include it.

POST
/v1/nodes/{nodeId}/reservations

Authorization

apiKey
headerAuthorizationBearer <token>

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

Path Parameters

nodeId*string

Request Body

application/json
  1. body
unitIds*array<string>

GPU unit ids to reserve (from the node's inventory). Must be sellable units of a reservable class (vfio-group or device-request), and the node must be single-class.

allowedOrgIds*array<string>

The audience. The platform ops org is added automatically so we can validate the node.

managingOrgIds?array<string>

Orgs allowed to release, reclaim, and terminate spot workloads on these units on the owner's behalf while the reservation is active and inside its term. Omit unless a second org manages this capacity commercially.

startsAt?string

Defaults to now

endsAt?string

Omit for open-ended

contractRef?string
reason?string

Response Body

Created

application/json
  1. response

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.

id*string
nodeId*string
reservedUnitIds*array<string>
releasedUnitIds?array<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.

allowedOrgIds*array<string>

The audience: orgs that may place workloads on the reserved units.

managingOrgIds?array<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, while the reservation is active and inside its term. Being in the audience does not confer this.

startsAt*string
endsAt?string

Absent = open-ended until cancelled

status*string

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.

Value in"pending""active""expired""cancelled""needs-review"
topologyGen?integer

Node topology generation this reservation was written against

contractRef?string
reason?string
createdAt?string
updatedAt?string
terminated?array<string>

Reclaim only: spot VM ids terminated to free the reclaimed units.

skipped?array<string>

Reclaim only: VM ids left running because they are not spot.

wouldTerminate?array<string>

Reclaim dry run only: the spot VM ids this call would terminate.

wouldSkip?array<string>

Reclaim dry run only: VM ids that would be left running.

Example Request
curl -X POST 'https://api.openrelay.inc/v1/nodes/string/reservations' \  -H 'Content-Type: application/json' \  -d '{  "unitIds": [    "string"  ],  "allowedOrgIds": [    "string"  ]}'
Example Response
{  "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 a node's reservations GET

Returns every reservation on one node, each with its reserved unit ids, the units released to spot, its audience, managing orgs, term and status. Readable by a platform operator, the org that owns the node, and any org managing a reservation on it that is active and inside its term. Anyone else gets 404.

Get one node reservation GET

Returns one reservation on a node: its reserved unit ids, the units currently released to spot, its audience, managing orgs, term and status. Readable by the same orgs as the list: a platform operator, the org that owns the node, and any org managing a reservation on it that is active and inside its term.