Docs
Reservations

File a capacity request for an org

POST
/v1/operator/capacity-requests

Records a capacity request in another org, as that org's own POST /v1/capacity-requests would, for GPUs we agreed with it outside the console, such as under a contract. The request is open and holds nothing until it is granted. The org reads in its own audit log that we filed it. Requires Idempotency-Key.

Only an owner of our own org holds capacity:grant, and only with a token issued to our console.

Authorization

oauth2 capacity:grant
headerAuthorizationBearer <token>

A person's access token, sent as Authorization: Bearer <token>, from the authorization code flow with PKCE (S256). A CLI on a machine without a browser can use the device flow (RFC 8628) at https://auth.confidential.ai/oauth2/device_authorization instead. Ask for the resource https://api.cloud.confidential.ai (RFC 8707): a token issued for any other resource, the MCP server's included, is refused. A token acts for one person in one org, with the scopes of the person's role there whatever the client asks for, so ask the authorization server for none of the scopes below; they are listed so that each operation can name the ones it needs. Access tokens last minutes, and a refresh token is replaced at every use.

Scope: capacity:grant

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

A capacity request we file for another org.

org*OrgId

The org the request is for.

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

The GPUs an org asks for.

Response Body

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

application/json
  1. response

A capacity request with the org that made it, as our own org's owners see it.

org*
capacityRequest*

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.

Example Request
curl -X POST 'https://api.cloud.confidential.ai/v1/operator/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 '{  "org": "org-acme",  "request": {    "gpuModel": "b300",    "gpuCount": 16,    "term": "P90D",    "start": "2027-03-01T00:00:00Z",    "locations": [      "us-west-1"    ],    "displayName": "Contract"  }}'
Example Response
{  "org": {    "id": "org-acme",    "name": "Acme"  },  "capacityRequest": {    "id": "cq-7hd2m4x9qk",    "displayName": "Contract",    "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"    ],    "requestedBy": {      "userId": "user_01JB2M5V9Q7X3K8N4T6W0YHZ",      "agent": false    },    "createdAt": "2026-11-14T18:02:11Z",    "expiresAt": "2027-02-12T18:02:11Z"  }}