API reference

Credits & payments

Check how much you can still spend, add prepaid credit, and keep the balance topped up automatically - all from the API, with the same card, invoices and receipts as the Billing page.

Balance and caps

GET/v1/credits

Authenticate with your API key as usual. The call is free and works even when the balance is empty, so you can check it from a job before a large run, or alert when it gets low.

bash

curl https://boldrouter.com/v1/credits \
  -H "Authorization: Bearer $BOLD_API_KEY"

Response

json

{
  "object": "credits",
  "currency": "USD",
  "period": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-11-01T00:00:00.000Z" },
  "balance": { "prepaid_usd": 84.2, "held_usd": 0.35, "available_usd": 83.85 },
  "account_spend_usd": 41.07,
  "key": { "id": "key_8f3a…", "name": "Production", "spend_usd": 12.5 },
  "caps": {
    "key": { "monthly_cap_usd": 50, "used_usd": 12.5, "remaining_usd": 37.5 },
    "member": null
  },
  "remaining_usd": 37.5
}

Field	Type	Description
period	object	The calendar month (UTC) the spend figures cover. Spend and caps reset at `end`.
balance	object \| null	The account's prepaid balance. `held_usd` is reserved for requests still running; `available_usd` is what new requests can use. `null` for workspace members - see who sees what.
account_spend_usd	number \| null	Spend on the whole account this month, every key and product. `null` for workspace members.
key	object	The key you called with, and its spend this month.
caps.key	object	The key's monthly cap, set on the API keys page. `monthly_cap_usd` and `remaining_usd` are `null` when the key has no cap.
caps.member	object \| null	For a workspace member's key: their monthly API budget, set by an admin. `null` for account-level keys.
remaining_usd	number \| null	What you can still spend this month: the smallest of the available balance and each cap's remaining amount. `null` when nothing you can see limits it.

Who sees what

Account owners, admins and account-level keys see everything, including the account's balance and total spend.
Other workspace members see their own key and budget only; balance and account_spend_usd are null.
Keys limited to MCP scopes need billing:read.

When a request is refused with 402 insufficient_quota, this endpoint tells you which limit was reached: the balance, the key's cap or the member budget. See Errors & rate limits. Department budgets in boldworkspaces apply to workspace chat only, so they don't limit API calls and aren't listed here.

Allowing a key to make payments

Adding credit and changing auto-recharge charge your card, so they need a key created for it. On the API keys page, tick Choose this key's scopes and include billing:write. Existing keys and keys without scopes can never make payments. The key must belong to the account or to a workspace owner or admin.

Add credit

POST/v1/credits/topup

Charges the card saved on the Billing page and adds the amount to your prepaid balance. The card is charged the amount plus the platform fee, and you get the usual invoice and receipt.

bash

curl https://boldrouter.com/v1/credits/topup   -H "Authorization: Bearer $BOLD_PAYMENTS_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: $(uuidgen)"   -d '{"amount": 50}'

Field	Type	Description
amount*	number	Credit to add, in USD: 5 to 10,000.
Idempotency-Key*	header	A unique value per top-up, e.g. a UUID (8 to 255 characters). Sending the same key again returns the first result without charging again, so retrying after a timeout is safe. Reusing a key with a different amount is refused (`422`).

json

{
  "object": "topup",
  "id": "tu_5f2c…",
  "status": "succeeded",
  "amount_usd": 50,
  "fee_usd": 2.75,
  "charged_usd": 52.75,
  "balance_usd": 134.2,
  "invoice": { "id": "in_…", "number": "BR-0042", "url": "https://invoice.stripe.com/…", "pdf": "https://…" },
  "checkout_url": null,
  "failure_reason": null,
  "idempotency_key": "6f1d…",
  "created": 1793001600
}

status tells you what happened:

succeeded - the card was charged and balance_usd is the new balance.
checkout_required - no card is saved yet. Open checkout_url to pay; the credit is added as soon as the payment completes. Nothing is charged until then.
failed (HTTP 402) - the card was declined; failure_reason says why and nothing was credited. When the bank requires the cardholder to confirm the payment, checkout_url lets them finish it there.

At most 5 card top-ups per account in any 24 hours go through the API (429 after that), and every charge emails a receipt to the account owner. Treat a billing:write key like a card: keep it out of client code and rotate it if it leaks.

Auto-recharge

POST/v1/credits/auto-recharge

Keeps the balance topped up: when it falls below threshold, the saved card is charged for amount of credit (plus the platform fee). It's the same setting as auto top-up on the Billing page.

bash

curl https://boldrouter.com/v1/credits/auto-recharge   -H "Authorization: Bearer $BOLD_PAYMENTS_KEY"   -H "Content-Type: application/json"   -d '{"threshold": 20, "amount": 100}'

Field	Type	Description
threshold	number	Recharge when the balance falls below this, in USD: 1 to 1,000.
amount	number	Credit added each time, in USD: 10 to 10,000.
enabled	boolean	Send `false` to switch auto-recharge off. Anything else switches it on.

json

{
  "object": "auto_recharge",
  "enabled": true,
  "threshold": 20,
  "amount": 100,
  "card": { "brand": "visa", "last4": "4242" },
  "max_per_day": 3,
  "disabled_reason": null,
  "setup_url": null
}

With no card saved, the settings are kept but auto-recharge stays off, and setup_url links to a page to save one. Call the endpoint again once the card is saved to switch it on. GET /v1/credits/auto-recharge returns the current settings (needs billing:read). After three failed charges in a row it switches itself off and disabled_reason says why.