Credit, debit, or adjust budget allocation
Modifies budget allocation and remaining balance outside the reservation flow. Common operations:
AUTHORIZATION: - ApiKeyAuth: Tenant can fund their own budgets only (scoped by authenticated tenant) - AdminKeyAuth: Accepted as alternative (dual-auth).
When using AdminKeyAuth, tenant_id query parameter is REQUIRED for scoping.
CREDIT (top-up): - allocated += amount - remaining += amount - Use for: monthly allocations, bonus credits
DEBIT (drain): - allocated -= amount - remaining -= amount (fails if would go negative) - Use for: downgrades, refunds, policy enforcement
RESET (resize allocated): - allocated = amount - remaining = amount - reserved - spent - debt - spent, reserved, debt all preserved - Use for: plan changes, limit adjustments, ceiling resize - NOT the operation for billing-period boundaries — see RESET_SPENT
RESET_SPENT (new billing period): - allocated = amount - spent = (request.spent if supplied, else 0) - remaining = allocated - spent - reserved - debt - reserved preserved (active reservations straddle the period
and will land in the new period's spent when they commit)
- debt preserved (periods don't forgive debt; use REPAY_DEBT) - Optional
spentfield supports: migration from other billing
systems (start with existing consumption), prorated mid-period
signup, credit-back/compensation, state correction.
Must be >= 0 when supplied. Default 0 covers routine period
rollovers. - Emits
budget.reset_spentevent (distinct frombudget.reset)
withspent_override_providedflag so compliance dashboards
can distinguish routine rollovers from explicit adjustments.
REPAY_DEBT: - debt -= amount (use remaining if debt < amount) - Use for: manual debt reconciliation
IDEMPOTENCY: - Required idempotency_key prevents double-funding - Replayed requests return original response
Authorizations
Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)
Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.
Parameters
Query Parameters
When using ApiKeyAuth: ignored — the authenticated tenant from the API key is always used for scoping. When using AdminKeyAuth: REQUIRED — specifies which tenant's budget to fund. Returns 400 if missing when using AdminKeyAuth.
Canonical scope identifier, e.g., "tenant:acme" or "tenant:acme/workspace:prod"
"USD_MICROCENTS""TOKENS""CREDITS""RISK_POINTS"Request Body
Responses
Funding operation completed