Cycles

Appearance

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: - ApiKeyAuth (X-Cycles-API-Key): tenant creates budgets for their own
scopes only. tenant_id is implicit from the authenticated key and
MUST NOT appear in the request body.

  • AdminKeyAuth (X-Admin-API-Key): admin operator creates a budget on
    behalf of a tenant. tenant_id is REQUIRED in the request body so
    the server can route the operation to the correct tenant. The
    audit-log entry records actor_type=ADMIN_ON_BEHALF_OF for these
    calls so security review can distinguish admin-driven creates
    from tenant self-service. Matches the existing dual-auth pattern
    on listBudgets and fundBudget.

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)
or
AdminKeyAuth

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.

Type
API Key (header: X-Admin-API-Key)

Request Body​

application/json
JSON
{
  
"tenant_id": "string",
  
"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",
  
"tenant_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"
}

Playground​

Authorization
Body

Samples​

Powered by VitePress OpenAPI