Request a GPU reservation
Requests the GPUs in an offering for its term. Requires
Idempotency-Key. Returns 202 with the reservation.
A request made with an agent credential starts awaiting_approval,
with an approval whose url an owner of the org opens in our
console to approve or decline it within 72 hours: hand that link to
a person. Approved, it becomes requested; declined, or undecided
by approval.expiresAt, it becomes declined. Any other request
starts requested.
A requested reservation is invoiced for its total, in invoice:
emailed to your org's billing email and due 10 days after the
request or at the reservation's start, whichever is first. A card
on file is never charged for it.
Paying it confirms the reservation; one still unpaid at
invoice.dueAt is declined. Once confirmed, a reservation cannot
be withdrawn or refunded. You can withdraw a request with DELETE
until it is confirmed, which voids its invoice.
When the window opens the reservation becomes active, and
POST /v1/instances with reservation and a GPU size launches
instances against it: any size of its GPU model with reservation
in purchaseOptions, so its GPUs are split across sizes as you
like. At the end of the term the platform deletes those instances.
AuthorizationBearer <cc_...>An API key of your org, sent as Authorization: Bearer cc_.... Keys
start with cc_ and are otherwise opaque. Treat a key as a password:
anyone holding it can act with its scopes until it expires or is
revoked. Each operation's security requirement lists the scopes it
needs; an empty list means any valid key. The MCP server at /mcp
accepts agent keys and no other kind.
Scope: reservations:write
Idempotency-Key*stringA unique key for this intent, such as a UUID. Reuse it for every
retry of the same request. A missing key returns
400 idempotency_key_required. See Idempotency above.
^[!-~]+$1 <= length <= 255Api-Version*stringThe API version the request is written against. This document
describes 2026-10-15. A missing header returns
400 api_version_required, and a version the API does not serve
returns 400 unsupported_api_version.
X-Correlation-ID?stringAn id of your own for this request, or for a group of requests, to
find them in our logs and yours. Logged with the request and returned
unchanged in X-Correlation-ID. The request id itself is always the
API's own, in X-Request-ID.
^[A-Za-z0-9._:-]+$1 <= length <= 128Org-Context?stringAdmin keys only: the id of the org to act in. Required with an admin
key, together with Access-Reason; with any other credential it
returns 400 invalid_request. Every request that carries it is
recorded in that org's operator-access log.
^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$5 <= length <= 63Access-Reason?stringAdmin keys only: why the operator is acting in the org, such as a
support ticket. Required with Org-Context. Recorded, verbatim, in
the org's operator-access log.
^[^\x00-\x1F\x7F]+$10 <= length <= 500application/json- body
A request for the GPUs in an offering.
offering*ReservationOfferingIdThe id of an offering from GET /v1/reservation-offerings. An id
that has expired, been taken or is unknown returns
409 offering_expired; one that is not an offering id at all
returns 400 invalid_request.
^ro-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63displayName?ReservationDisplayNameA name for people, shown with the reservation. It need not be
unique and never identifies the reservation; use its id.
^[^\x00-\x1F\x7F]+$1 <= length <= 63Accepted. A request made with an agent credential is
awaiting_approval until an owner of the org decides on it in our
console; any other is requested until its invoice is paid, which
confirms it. A replay returns its current state.
application/json- response
Whole GPUs held for your org over a term.
id*ReservationIdOpaque. Starts with r-; otherwise as instance ids.
^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63displayName?stringThe display name the request gave. Absent if none.
status*ReservationStatusOpen set; accept values not listed. awaiting_approval: requested
with an agent credential, and waiting for an owner of the org to
approve it in our console; you can withdraw it. requested: waiting
for its invoice to be paid; you can withdraw it, which voids the
invoice. confirmed: paid for, and ours to honour; cannot be
withdrawn. active: the window is open and GPU instances
can launch. ended: the window closed and its instances were
deleted. declined and withdrawn: closed before confirmation.
statusChangedAt*stringdate-timestatusMessage?stringA note on the status, such as why a request was declined. Do not parse it.
approval?Only for a reservation requested with an agent credential: the approval of an owner of the org that it waits for, or got.
offering*ReservationOfferingIdOpaque. Starts with ro-; otherwise as instance ids.
^ro-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63location*LocationIdA location id from GET /v1/locations, such as us-west-1.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 63tee*TeeThe trusted execution environment. Open set; accept values not listed.
gpu*GPUs, whole and passed through to the guest. Each instance gets its count of the host's GPUs, which the host's device plugin picks, and only those GPUs are passed to it. With 8 GPUs the guest has the whole board and can attest its NVSwitch topology. With 1, 2 or 4, it shares the board's NVSwitches with other instances on the host, which the guest cannot verify, and separation between instances over NVLink is not yet verified.
start*stringdate-timeend*stringdate-timeterm*TermA whole number of days, as an ISO 8601 duration, from P7D to P365D.
^P([7-9]|[1-9][0-9]|[12][0-9]{2}|3[0-5][0-9]|36[0-5])D$price*The list price for the whole term, and what your org pays instead if it has a contract for the GPU model.
invoice?The invoice for the reservation's total, once it is requested.
Absent before then, and while billing is not set up.
gpusInUse*integerGPUs that instances in the reservation use right now.
0 <= valuerequestedBy*Who requested the reservation, so that an owner deciding on an
agent's request sees who asked. An agent's request carries
approval.
createdAt*stringdate-timecurl -X POST 'https://api.cloud.confidential.ai/v1/reservations' \ -H 'Idempotency-Key: 0b9d6c1e-5f8a-4c2e-9a51-2f7e0c3d4b18' \ -H 'Api-Version: 2026-10-15' \ -H 'X-Correlation-ID: rollout-2026-10-22' \ -H 'Access-Reason: Support ticket 4821: customer asked why i-6d3f9h2k8mzr failed' \ -H 'Content-Type: application/json' \ -d '{ "offering": "ro-3hx8k2", "displayName": "November training run"}'{ "id": "r-5mf2k9x3qp", "displayName": "November training run", "status": "requested", "statusChangedAt": "2026-10-22T17:40:00Z", "offering": "ro-3hx8k2", "location": "us-west-1", "tee": "tdx", "gpu": { "model": "b300", "count": 8 }, "start": "2026-11-02T00:00:00Z", "end": "2026-12-02T00:00:00Z", "term": "P30D", "price": { "currency": "USD", "perGpuHour": "7.00", "total": "40320.00" }, "invoice": { "status": "open", "url": "https://invoice.stripe.com/i/acct_1Example/test_YWNjdF8xRXhhbXBsZQ", "dueAt": "2026-11-01T17:40:00Z" }, "gpusInUse": 0, "requestedBy": { "userId": "user_01J8ZQ4X3N2M5K7P9R6T", "agent": false }, "createdAt": "2026-10-22T17:40:00Z"}