API examples

Every endpoint a grant owner can call, with real requests and responses. The full endpoint list is in the generated API reference.

$SPEND_TOKEN is an accepted ChirpAuth token (see Authentication); you cannot get one today. $SPEND stands for the base URL:

SPEND=https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws

Create a grant

POST /v1/spend/grants

curl "$SPEND/v1/spend/grants" \
  -H "Authorization: Bearer $SPEND_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_id": "acme.agent", "limit_units": 5000, "per_call_cap": 500, "period": "day"}'

The owner is always the caller; no field names another.

Response, 201 Created. The owner’s wallet is empty, so available is 0 (see Wallets):

{
  "id": "f9e67456-f00d-4abe-a736-e8c2528f04ed",
  "owner_uid": "sub_8Q3K2M11XZ",
  "app_id": "acme.agent",
  "limit_units": 5000,
  "per_call_cap": 500,
  "period": "day",
  "revoked": false,
  "settlement": "Prepaid",
  "available": 0
}

A Byok grant, {"app_id": "acme.research", "limit_units": 20000, "period": "month", "settlement": "Byok"}, doesn’t use the wallet, so it can draw at once:

{
  "id": "eb3d8a3f-2da8-42a4-9549-a108a38c6a94",
  "owner_uid": "sub_8Q3K2M11XZ",
  "app_id": "acme.research",
  "limit_units": 20000,
  "per_call_cap": 20000,
  "period": "month",
  "revoked": false,
  "settlement": "Byok",
  "available": 20000
}

period is left out of the response when the grant has none.

If the owner already has an unrevoked grant for that app_id, the response is 409:

{"error": "an active grant for this app already exists; revoke it first"}

List your grants

GET /v1/spend/grants returns every grant you own, revoked ones included, as an array of the shape above, in no particular order.

Read a grant’s balance

GET /v1/spend/grants/{grant_id}/balance

curl "$SPEND/v1/spend/grants/eb3d8a3f-2da8-42a4-9549-a108a38c6a94/balance" \
  -H "Authorization: Bearer $SPEND_TOKEN"

Response, 200 OK, after a service settled 120 units and holds 300 more:

{
  "grant_id": "eb3d8a3f-2da8-42a4-9549-a108a38c6a94",
  "limit_units": 20000,
  "debited": 120,
  "reserved": 300,
  "available": 19580
}

Balances explains each field. A grant you don’t own is 404 with {"error":"unknown grant"}.

List your usage

GET /v1/spend/usage returns your settled usage across all your grants:

[
  {
    "authorization_id": "19cce8ae-aa3c-426d-a56a-cecdc8ee6fa7",
    "grant_id": "eb3d8a3f-2da8-42a4-9549-a108a38c6a94",
    "settled_units": 120,
    "settled_at": "2026-11-05T20:41:00.143975439Z"
  }
]

authorization_id names the reservation the units were settled against. Open reservations are not listed; they show as reserved in the balance.

Change a grant’s limit

PATCH /v1/spend/grants/{grant_id} with {"limit_units": <n>} returns the grant. A limit below debited plus reserved is 409:

{"error": "limit cannot drop below consumed-or-reserved usage"}

The new limit is what the grant may draw from then on. See Changing a limit.

Revoke a grant

DELETE /v1/spend/grants/{grant_id} returns 204 No Content with no body. Revoking a grant that is already revoked also returns 204. See Grants.

Public endpoints

curl -fsS https://fwkl7sygagsdlb6ut3lsomjmvi0qvyyt.lambda-url.us-east-1.on.aws/health