Create a budget ledger for a scope
POST
/v1/admin/budgets
Initializes a new budget ledger for a (scope, unit) pair. This must be done before any reservations can be made against the scope.
AUTHORIZATION: - Tenant can create budgets for their own scopes only - Uses ApiKeyAuth (X-Cycles-API-Key) - tenant manages own budgets
SCOPE VALIDATION: - Scope must match pattern: tenant:* or tenant:/workspace: etc. - Tenant must exist and be ACTIVE - Cannot create duplicate (scope, unit) ledgers
INITIAL STATE: - allocated = requested amount - remaining = allocated - reserved = spent = debt = 0
Authorizations
ApiKeyAuth
Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)
Type
API Key (header: X-Cycles-API-Key)
Request Body
application/json
JSON "scope": "string", "unit": "string", "allocated": { "unit": "string", "amount": 0 }, "overdraft_limit": { "unit": "string", "amount": 0 }, "commit_overage_policy": "string", "rollover_policy": "NONE", "period_start": "string", "period_end": "string", "metadata": { "additionalProperties": "string" }
{
}
Responses
Budget created
application/json
JSON "ledger_id": "string", "scope": "string", "scope_path": "string", "unit": "string", "allocated": { "unit": "string", "amount": 0 }, "remaining": { "unit": "string", "amount": 0 }, "reserved": { "unit": "string", "amount": 0 }, "spent": { "unit": "string", "amount": 0 }, "debt": { "unit": "string", "amount": 0 }, "overdraft_limit": { "unit": "string", "amount": 0 }, "is_over_limit": true, "commit_overage_policy": "string", "status": "string", "rollover_policy": "string", "period_start": "string", "period_end": "string", "created_at": "string", "updated_at": "string"
{
}