spend
Cloud work an AI agent's key asked for beyond the free allowance, held until a person confirms it. The agent's call answers 202 with a hold. A person approves or denies the hold from the Inbox. Approving creates the job under the agent's recorded request, attributed to its key.
GET /v1/spend/holds
List held cloud spend
The holds the caller can see, newest first: those on their own account, on an organization they belong to, and those their keys filed. A key limited to repos sees only the holds it filed itself. status narrows the list. A pending hold past its expires_at reads as expired.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
status | query | SpendHoldStatus | |
limit | query | integer | Page size. |
cursor | query | string | Opaque cursor from the previous page's |
Responses
| Status | Description | Body |
|---|---|---|
200 | Page of holds. | SpendHoldPage |
401 | Missing or invalid credentials. | Problem |
422 | Request failed validation. | Problem |
GET /v1/spend/holds/{hold_id}
Get one held request
One hold, with what was asked, the estimate, what approving would reserve, the free allowance's share, and the account's spend cap as it stands now. An agent polls this after a 202. A hold the caller may not see is 404.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
hold_id | path | Id | Held request id ( |
Responses
POST /v1/spend/holds/{hold_id}/approve
Approve a held request and create its job (web session only)
A person of the account confirms the spend. session scope: no API key of any scope may approve, so an agent cannot confirm its own hold. The hub then creates the job from the recorded request, as the key that asked, with the agent limit lifted for this one job. The job is attributed to that key for usage. The reservation is taken now, and the account's spend cap is applied now, not when the hold was filed. A 429 leaves the hold pending. A hold that is no longer pending, or whose key no longer works, is 409. Audited as spend.approve.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
hold_id | path | Id | Held request id ( |
Responses
| Status | Description | Body |
|---|---|---|
200 | Approved, with the job's id in | SpendHold |
401 | Missing or invalid credentials. | Problem |
403 | Authenticated but not allowed (visibility, membership or scope). | Problem |
404 | Resource not found (or hidden from the caller). | Problem |
409 | State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...). | Problem |
422 | Request failed validation. | Problem |
429 | The account's spend cap is in | Problem |
503 | A service this endpoint needs is not configured in this deployment. The API boots with zero secrets. An endpoint that needs one says so instead of returning a stack trace. | Problem |
POST /v1/spend/holds/{hold_id}/deny
Deny a held request with a reason (web session only)
A person says no, and says why. The reason goes into the record the agent reads. session scope, like approving. 409 when the hold is no longer pending. Audited as spend.deny.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
hold_id | path | Id | Held request id ( |
Request body
| Field | Type | Description |
|---|---|---|
reason | string | Why it is denied. It goes into the record the agent reads. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Denied. | SpendHold |
401 | Missing or invalid credentials. | Problem |
403 | Authenticated but not allowed (visibility, membership or scope). | Problem |
404 | Resource not found (or hidden from the caller). | Problem |
409 | State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...). | Problem |
422 | Request failed validation. | Problem |
POST /v1/spend/holds/{hold_id}/cancel
Withdraw a held request
The key that filed the hold, or a person of the account, takes it back. Nothing was started, so nothing is undone. 409 when the hold is no longer pending. Audited as spend.cancel.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
hold_id | path | Id | Held request id ( |
Responses
| Status | Description | Body |
|---|---|---|
200 | Canceled. | SpendHold |
401 | Missing or invalid credentials. | Problem |
403 | Authenticated but not allowed (visibility, membership or scope). | Problem |
404 | Resource not found (or hidden from the caller). | Problem |
409 | State conflict (duplicate handle/slug, wrong repo kind, terminal job, ...). | Problem |
Schemas (2)
The schemas these operations reach before any other tag’s do. A type that links elsewhere is rendered on that tag’s page.
SpendHoldPage
| Field | Type | Description |
|---|---|---|
items | array of SpendHold | |
next_cursor | string | null |
SpendHoldDecision
| Field | Type | Description |
|---|---|---|
reason | string | Why it is denied. It goes into the record the agent reads. |