Docs
Reservations

Decline an agent's GPU reservation

POST
/v1/reservations/{id}/decline

Declines a GPU reservation that an agent credential requested and that is awaiting_approval. It becomes declined, with approval.status declined. Requires Idempotency-Key, and reservations:approve, as approving does. Declining it again returns it unchanged; one that was approved, lapsed or withdrawn, or needed no approval, returns 409 invalid_state.

Authorization

oauth2 reservations:approve
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: reservations:approve

Path Parameters

id*string

The reservation id.

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

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

Response Body

The reservation after the decision: requested once approved, to be invoiced, or declined. A repeat of the same decision returns its current state.

application/json
  1. response

Whole GPUs held for your org over a term.

id*ReservationId

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

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

The display name the request gave. Absent if none.

status*ReservationStatus

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

A 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*ReservationOfferingId

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

Match^ro-[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Lengthlength <= 63
location*LocationId

A location id from GET /v1/locations, such as us-west-1.

Match^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
Length1 <= length <= 63
tee*Tee

The 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*string
Formatdate-time
end*string
Formatdate-time
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$
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*integer

GPUs that instances in the reservation use right now.

Range0 <= value
requestedBy*

Who requested the reservation, so that an owner deciding on an agent's request sees who asked. An agent's request carries approval.

createdAt*string
Formatdate-time
Example Request
curl -X POST 'https://api.cloud.confidential.ai/v1/reservations/r-5mf2k9x3qp/decline' \  -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'
Example Response
{  "id": "r-8kd3m1x7qz",  "displayName": "Fine-tuning run",  "status": "requested",  "statusChangedAt": "2026-10-22T19:05:00Z",  "approval": {    "status": "approved",    "url": "https://console.example/approvals/r-8kd3m1x7qz",    "expiresAt": "2026-10-25T17: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"  },  "gpusInUse": 0,  "requestedBy": {    "apiKey": {      "id": "k-7k2m9q4x1bfa",      "name": "training-agent"    },    "agent": true  },  "createdAt": "2026-10-22T17:40:00Z"}