Docs
Reservations

Ask for GPU capacity

POST
/v1/capacity-requests

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.

Authorization

headerAuthorizationBearer <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

Header Parameters

Idempotency-Key*string

A 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.

Match^[!-~]+$
Length1 <= length <= 255
Api-Version*string

The 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?string

An 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.

Match^[A-Za-z0-9._:-]+$
Length1 <= length <= 128
Org-Context?string

Admin 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.

Match^org-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length5 <= length <= 63
Access-Reason?string

Admin 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.

Match^[^\x00-\x1F\x7F]+$
Length10 <= length <= 500

Request Body

application/json
  1. body

The GPUs an org asks for.

gpuModel*GpuModel

The GPU model you want.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 32
gpuCount*integer

How many GPUs: the GPU count of one of the model's sizes in GET /v1/sizes, or a multiple of the largest.

Range1 <= value <= 512
term*Term

How long you want the GPUs for.

Match^P([7-9]|[1-9][0-9]|[12][0-9]{2}|3[0-5][0-9]|36[0-5])D$
start?string

The start you want, 00:00 UTC on a day that has not begun, at most two years ahead. Without it, as soon as possible.

Formatdate-time
locations?array<>

The locations you would take. Without it, any.

Items1 <= items <= 16
tees?array<>

The TEEs you would take. Without it, any.

Items1 <= items <= 8
displayName?ReservationDisplayName

A name for people, shown with the request. It need not be unique and never identifies the request; use its id.

Match^[^\x00-\x1F\x7F]+$
Length1 <= length <= 63
note?CapacityRequestNote

Anything else we should know, such as how the GPUs should be placed.

Match^[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]+$
Length1 <= length <= 1000

Response Body

The capacity request, open. A replay returns its current state.

application/json
  1. 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*CapacityRequestId

Opaque. Starts with cq-; otherwise as instance ids.

Match^cq-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
displayName?string

The display name the request gave. Absent if none.

status*CapacityRequestStatus

Open 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*string
Formatdate-time
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.

term*Term

A whole number of days, as an ISO 8601 duration, from P7D to P365D.

Match^P([7-9]|[1-9][0-9]|[12][0-9]{2}|3[0-5][0-9]|36[0-5])D$
start?string

The start the request asked for. Absent if it asked for as soon as possible.

Formatdate-time
locations?array<>

The locations the request would take. Absent if any.

tees?array<>

The TEEs the request would take. Absent if any.

note?string

The 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*string
Formatdate-time
expiresAt*string

When an open request becomes expired, 90 days after it was made.

Formatdate-time
reservation?ReservationId

The reservation we made for a granted request, which holds its GPUs and is invoiced. Absent otherwise.

Match^r-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
Example Request
curl -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."}'
Example Response
{  "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"}