Ask for GPU capacity
Tells us the GPUs your org wants: a model, a count, a term and,
if you like, a start and the locations you would take. Use it when
GET /v1/reservation-offerings has nothing that fits, or to ask
ahead for a date. Requires Idempotency-Key.
A capacity request holds no GPUs, has no price and is never
invoiced, so it needs no payment method. It stays open for 90
days, until expiresAt, and you can withdraw it with DELETE at
any time. An org may have 20 open requests.
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
The GPUs an org asks for.
gpuModel*GpuModelThe GPU model you want.
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$1 <= length <= 32gpuCount*integerHow many GPUs: the GPU count of one of the model's sizes in
GET /v1/sizes, or a multiple of the largest.
1 <= value <= 512term*TermHow long you want the GPUs for.
^P([7-9]|[1-9][0-9]|[12][0-9]{2}|3[0-5][0-9]|36[0-5])D$start?stringThe start you want, 00:00 UTC on a day that has not begun, at most two years ahead. Without it, as soon as possible.
date-timelocations?array<>The locations you would take. Without it, any.
1 <= items <= 16tees?array<>The TEEs you would take. Without it, any.
1 <= items <= 8displayName?ReservationDisplayNameA name for people, shown with the request. It need not be unique
and never identifies the request; use its id.
^[^\x00-\x1F\x7F]+$1 <= length <= 63note?CapacityRequestNoteAnything else we should know, such as how the GPUs should be placed.
^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]+$1 <= length <= 1000The capacity request, open. A replay returns its current state.
application/json- response
An org's ask for whole GPUs over a term, made whether or not any are free. It holds no GPUs and has no price.
id*CapacityRequestIdOpaque. Starts with cq-; otherwise as instance ids.
^cq-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63displayName?stringThe display name the request gave. Absent if none.
status*CapacityRequestStatusOpen set; accept values not listed. open: with us, and yours to
withdraw. granted: we reserved the GPUs for you, as reservation,
whose invoice confirms it. withdrawn: you withdrew it. expired:
it stayed open until expiresAt.
statusChangedAt*stringdate-timegpu*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.
term*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$start?stringThe start the request asked for. Absent if it asked for as soon as possible.
date-timelocations?array<>The locations the request would take. Absent if any.
tees?array<>The TEEs the request would take. Absent if any.
note?stringThe note the request gave. Absent if none.
requestedBy*Who made a change, by the credential it came with. Exactly one of
apiKey, userId, workload and operator is present.
createdAt*stringdate-timeexpiresAt*stringWhen an open request becomes expired, 90 days after it was made.
date-timereservation?ReservationIdThe reservation we made for a granted request, which holds its
GPUs and is invoiced. Absent otherwise.
^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$length <= 63curl -X POST 'https://api.cloud.confidential.ai/v1/capacity-requests' \ -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 '{ "gpuModel": "b300", "gpuCount": 16, "term": "P90D", "start": "2027-03-01T00:00:00Z", "locations": [ "us-west-1" ], "displayName": "Spring training run", "note": "Two full nodes on one fabric if you can."}'{ "id": "cq-7hd2m4x9qk", "displayName": "Spring training run", "status": "open", "statusChangedAt": "2026-11-14T18:02:11Z", "gpu": { "model": "b300", "count": 16 }, "term": "P90D", "start": "2027-03-01T00:00:00Z", "locations": [ "us-west-1" ], "note": "Two full nodes on one fabric if you can.", "requestedBy": { "userId": "user_01JB2M5V9Q7X3K8N4T6W0YHZ", "agent": false }, "createdAt": "2026-11-14T18:02:11Z", "expiresAt": "2027-02-12T18:02:11Z"}