Cycles

Appearance

v0.1.23

Complete Budget Governance System API​

Download OpenAPI Document
Complete budget governance protocol covering tenant management, authentication, and runtime enforcement (aligned with Cycles Protocol v0.1.23).

PURPOSE:
This specification defines a complete, interoperable budget governance system
with three integrated pillars:

  1. TENANT & BUDGET MANAGEMENT (Configuration Plane)

    • Tenant lifecycle: registration, hierarchy, metadata
    • Budget lifecycle: creation, allocation, funding, expiry
    • Policy configuration: caps, limits, quotas
    • API key provisioning and management

  2. AUTHENTICATION & AUTHORIZATION (Identity Plane)

    • API key validation and tenant resolution
    • Permission and scope enforcement
    • Key lifecycle: creation, rotation, revocation
    • Audit logging and access tracking

  3. RUNTIME ENFORCEMENT (Reservation Plane)

    • Budget reservations and commits (from Cycles Protocol v0.1.23)
    • Real-time enforcement with overdraft support
    • Balance queries and monitoring

DESIGN PRINCIPLES:

  • Interoperability: Standard schemas enable tool ecosystem
  • Security-first: Explicit trust boundaries and validation
  • Operational clarity: All workflows have defined endpoints
  • Backward compatibility: Extends Cycles v0.1.23 without breaking changes

DEPLOYMENT MODELS:

  • Single-service: All three pillars in one deployment
  • Split-plane: Separate admin/auth services from runtime enforcement
  • Federated: Multiple runtime enforcement instances, shared admin plane

Servers​

https://api.budget-governance.localDefault server

Tenants​

Pillar 1: Tenant registration and lifecycle management

Operations​

GET/v1/admin/tenantsPOST/v1/admin/tenantsGET/v1/admin/tenants/{tenant_id}PATCH/v1/admin/tenants/{tenant_id}

List all tenants​

GET
/v1/admin/tenants

Returns paginated list of all tenants. Useful for admin dashboards and tenant discovery.

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Query Parameters

status
Type
string
Valid values
"ACTIVE""SUSPENDED""CLOSED"
parent_tenant_id
Type
string
cursor
Type
string
limit
Type
integer
Minimum
1
Maximum
100
Default
50

Responses​

Tenant list

application/json
JSON
{
  
"tenants": [
  
  
{
  
  
  
"tenant_id": "string",
  
  
  
"name": "string",
  
  
  
"status": "string",
  
  
  
"parent_tenant_id": "string",
  
  
  
"default_commit_overage_policy": "string",
  
  
  
"default_reservation_ttl_ms": 60000,
  
  
  
"max_reservation_ttl_ms": 3600000,
  
  
  
"max_reservation_extensions": 10,
  
  
  
"reservation_expiry_policy": "AUTO_RELEASE",
  
  
  
"metadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
},
  
  
  
"created_at": "string",
  
  
  
"updated_at": "string",
  
  
  
"suspended_at": "string",
  
  
  
"closed_at": "string"
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Create a new tenant​

POST
/v1/admin/tenants

Registers a new tenant in the system. This is typically the first operation in onboarding a new organization.
AUTHORIZATION: - Requires admin key (X-Admin-API-Key)
IDEMPOTENCY: - Safe to retry with same tenant_id. Returns existing tenant if already created.

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Request Body​

application/json
JSON
{
  
"tenant_id": "string",
  
"name": "string",
  
"parent_tenant_id": "string",
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

Tenant already exists (idempotent)

application/json
JSON
{
  
"tenant_id": "string",
  
"name": "string",
  
"status": "string",
  
"parent_tenant_id": "string",
  
"default_commit_overage_policy": "string",
  
"default_reservation_ttl_ms": 60000,
  
"max_reservation_ttl_ms": 3600000,
  
"max_reservation_extensions": 10,
  
"reservation_expiry_policy": "AUTO_RELEASE",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"created_at": "string",
  
"updated_at": "string",
  
"suspended_at": "string",
  
"closed_at": "string"
}

Playground​

Authorization
Body

Samples​

Get tenant details​

GET
/v1/admin/tenants/{tenant_id}

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Path Parameters

tenant_id*
Type
string
Required

Responses​

Tenant details

application/json
JSON
{
  
"tenant_id": "string",
  
"name": "string",
  
"status": "string",
  
"parent_tenant_id": "string",
  
"default_commit_overage_policy": "string",
  
"default_reservation_ttl_ms": 60000,
  
"max_reservation_ttl_ms": 3600000,
  
"max_reservation_extensions": 10,
  
"reservation_expiry_policy": "AUTO_RELEASE",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"created_at": "string",
  
"updated_at": "string",
  
"suspended_at": "string",
  
"closed_at": "string"
}

Playground​

Authorization
Variables
Key
Value

Samples​

Update tenant properties​

PATCH
/v1/admin/tenants/{tenant_id}

Modify tenant metadata, status, or hierarchy.
STATUS TRANSITIONS: - ACTIVE → SUSPENDED: Blocks new reservations, existing active reservations can still commit/release - SUSPENDED → ACTIVE: Resume normal operations - * → CLOSED: Irreversible, archives tenant

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Path Parameters

tenant_id*
Type
string
Required

Request Body​

application/json
JSON
{
  
"name": "string",
  
"status": "string",
  
"metadata": {
  
}
}

Responses​

Tenant updated

application/json
JSON
{
  
"tenant_id": "string",
  
"name": "string",
  
"status": "string",
  
"parent_tenant_id": "string",
  
"default_commit_overage_policy": "string",
  
"default_reservation_ttl_ms": 60000,
  
"max_reservation_ttl_ms": 3600000,
  
"max_reservation_extensions": 10,
  
"reservation_expiry_policy": "AUTO_RELEASE",
  
"metadata": {
  
  
"additionalProperties": "string"
  
},
  
"created_at": "string",
  
"updated_at": "string",
  
"suspended_at": "string",
  
"closed_at": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Budgets​

Pillar 1: Budget ledger creation, allocation, and funding

Operations​

GET/v1/admin/budgetsPOST/v1/admin/budgetsPOST/v1/admin/budgets/{scope}/{unit}/fund

List budget ledgers​

GET
/v1/admin/budgets

Query budget ledgers by tenant, scope pattern, or status. Returns all units for matching scopes.
AUTHORIZATION: - Tenant can list their own budgets only (scoped by ApiKeyAuth)

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Parameters​

Query Parameters

tenant_id*
Type
string
Required
scope_prefix

Filter by scope prefix, e.g., "tenant:acme-corp/workspace:eng"

Type
string
unit
Type
string
Valid values
"USD_MICROCENTS""TOKENS""CREDITS""RISK_POINTS"
status
Type
string
Valid values
"ACTIVE""FROZEN""CLOSED"
cursor
Type
string
limit
Type
integer
Default
50

Responses​

Budget list

application/json
JSON
{
  
"ledgers": [
  
  
{
  
  
  
"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"
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

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"
}

Playground​

Authorization
Body

Samples​

Credit, debit, or adjust budget allocation​

POST
/v1/admin/budgets/{scope}/{unit}/fund

Modifies budget allocation and remaining balance outside the reservation flow. Common operations:
AUTHORIZATION: - Tenant can fund their own budgets only
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 (reallocate): - allocated = amount - remaining = amount - reserved - spent - debt - Use for: period rollovers, plan changes
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​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Parameters​

Path Parameters

scope*
Type
string
Required
unit*
Type
string
Required
Valid values
"USD_MICROCENTS""TOKENS""CREDITS""RISK_POINTS"

Request Body​

application/json
JSON
{
  
"operation": "string",
  
"amount": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"reason": "string",
  
"idempotency_key": "string",
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

Funding operation completed

application/json
JSON
{
  
"operation": "string",
  
"previous_allocated": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"new_allocated": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"previous_remaining": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"new_remaining": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"previous_debt": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"new_debt": {
  
  
"unit": "string",
  
  
"amount": 0
  
},
  
"timestamp": "string"
}

Playground​

Authorization
Variables
Key
Value
Body

Samples​

Policies​

Pillar 1: Policy and cap configuration

Operations​

GET/v1/admin/policiesPOST/v1/admin/policies

List policies​

GET
/v1/admin/policies

AUTHORIZATION: - Tenant can list their own policies only

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Parameters​

Query Parameters

scope_pattern
Type
string
status
Type
string
Valid values
"ACTIVE""DISABLED"
cursor
Type
string
limit
Type
integer
Default
50

Responses​

Policy list

application/json
JSON
{
  
"policies": [
  
  
{
  
  
  
"policy_id": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"scope_pattern": "string",
  
  
  
"priority": 0,
  
  
  
"caps": {
  
  
  
  
"max_tokens": 0,
  
  
  
  
"max_steps_remaining": 0,
  
  
  
  
"tool_allowlist": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"tool_denylist": [
  
  
  
  
  
"string"
  
  
  
  
],
  
  
  
  
"cooldown_ms": 0
  
  
  
},
  
  
  
"commit_overage_policy": "string",
  
  
  
"reservation_ttl_override": {
  
  
  
  
"default_ttl_ms": 0,
  
  
  
  
"max_ttl_ms": 0,
  
  
  
  
"max_extensions": 0
  
  
  
},
  
  
  
"rate_limits": {
  
  
  
  
"max_reservations_per_minute": 0,
  
  
  
  
"max_commits_per_minute": 0
  
  
  
},
  
  
  
"status": "string",
  
  
  
"effective_from": "string",
  
  
  
"effective_until": "string",
  
  
  
"created_at": "string",
  
  
  
"updated_at": "string"
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Create a policy with caps and limits​

POST
/v1/admin/policies

Defines caps (soft-landing constraints) and rate limits for scopes. Policies are evaluated during reservation requests.
AUTHORIZATION: - Tenant can create policies for their own scopes only
SCOPE PATTERNS: - "tenant:acme-corp" (exact match) - "tenant:acme-corp/" (all descendants) - "agent:" (all agents system-wide) - "*/agent:summarizer" (agent across all tenants)
PRIORITY: - Higher priority policies override lower priority - If multiple policies match, highest priority wins
EFFECTIVE DATES: - Optional time-bounded policies - Useful for temporary restrictions or trials

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
{
  
"name": "string",
  
"description": "string",
  
"scope_pattern": "string",
  
"priority": 0,
  
"caps": {
  
  
"max_tokens": 0,
  
  
"max_steps_remaining": 0,
  
  
"tool_allowlist": [
  
  
  
"string"
  
  
],
  
  
"tool_denylist": [
  
  
  
"string"
  
  
],
  
  
"cooldown_ms": 0
  
},
  
"commit_overage_policy": "string",
  
"reservation_ttl_override": {
  
  
"default_ttl_ms": 0,
  
  
"max_ttl_ms": 0,
  
  
"max_extensions": 0
  
},
  
"rate_limits": {
  
},
  
"effective_from": "string",
  
"effective_until": "string"
}

Responses​

Policy created

application/json
JSON
{
  
"policy_id": "string",
  
"name": "string",
  
"description": "string",
  
"scope_pattern": "string",
  
"priority": 0,
  
"caps": {
  
  
"max_tokens": 0,
  
  
"max_steps_remaining": 0,
  
  
"tool_allowlist": [
  
  
  
"string"
  
  
],
  
  
"tool_denylist": [
  
  
  
"string"
  
  
],
  
  
"cooldown_ms": 0
  
},
  
"commit_overage_policy": "string",
  
"reservation_ttl_override": {
  
  
"default_ttl_ms": 0,
  
  
"max_ttl_ms": 0,
  
  
"max_extensions": 0
  
},
  
"rate_limits": {
  
  
"max_reservations_per_minute": 0,
  
  
"max_commits_per_minute": 0
  
},
  
"status": "string",
  
"effective_from": "string",
  
"effective_until": "string",
  
"created_at": "string",
  
"updated_at": "string"
}

Playground​

Authorization
Body

Samples​

API Keys​

Pillar 2: API key provisioning and management

Operations​

GET/v1/admin/api-keysPOST/v1/admin/api-keysDELETE/v1/admin/api-keys/{key_id}

List API keys​

GET
/v1/admin/api-keys

Returns keys for a tenant. Full key secrets are never returned, only prefixes and metadata.

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Query Parameters

tenant_id*
Type
string
Required
status
Type
string
Valid values
"ACTIVE""REVOKED""EXPIRED"
cursor
Type
string
limit
Type
integer
Default
50

Responses​

API key list

application/json
JSON
{
  
"keys": [
  
  
{
  
  
  
"key_id": "string",
  
  
  
"tenant_id": "string",
  
  
  
"key_prefix": "string",
  
  
  
"name": "string",
  
  
  
"description": "string",
  
  
  
"permissions": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"scope_filter": [
  
  
  
  
"string"
  
  
  
],
  
  
  
"status": "string",
  
  
  
"created_at": "string",
  
  
  
"last_used_at": "string",
  
  
  
"expires_at": "string",
  
  
  
"revoked_at": "string",
  
  
  
"revoked_reason": "string",
  
  
  
"metadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Create an API key for a tenant​

POST
/v1/admin/api-keys

Provisions a new API key bound to a tenant. This is the only time the full key secret is returned. Store it securely.
KEY FORMAT: - Prefix: cyc_live_{random} or cyc_test_{random} - Random part: 32 characters, cryptographically random - Stored as: bcrypt hash of full key
PERMISSIONS: - Default for tenant keys: [reservations:, balances:read] - Admin keys: [admin:, reservations:, balances:] - Can be restricted to specific scopes via scope_filter
EXPIRY: - Recommended: 90 days for security - Can be set indefinitely but not recommended - Expired keys auto-fail validation

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Request Body​

application/json
JSON
{
  
"tenant_id": "string",
  
"name": "string",
  
"description": "string",
  
"permissions": [
  
  
"string"
  
],
  
"scope_filter": [
  
  
"string"
  
],
  
"expires_at": "string",
  
"metadata": {
  
}
}

Responses​

API key created

application/json
JSON
{
  
"key_id": "string",
  
"key_secret": "string",
  
"key_prefix": "string",
  
"tenant_id": "string",
  
"permissions": [
  
  
"string"
  
],
  
"created_at": "string",
  
"expires_at": "string"
}

Playground​

Authorization
Body

Samples​

Revoke an API key​

DELETE
/v1/admin/api-keys/{key_id}

Immediately revokes a key. The key will fail validation from this point forward. Active reservations using this key can still be committed/released, but no new operations are permitted.
REVOCATION IS PERMANENT: - Cannot be undone - Revoked keys remain in database for audit trail - Status transitions: ACTIVE → REVOKED

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Path Parameters

key_id*
Type
string
Required

Query Parameters

reason
Type
string
Max Length
512

Responses​

Key revoked

application/json
JSON
{
  
"key_id": "string",
  
"tenant_id": "string",
  
"key_prefix": "string",
  
"name": "string",
  
"description": "string",
  
"permissions": [
  
  
"string"
  
],
  
"scope_filter": [
  
  
"string"
  
],
  
"status": "string",
  
"created_at": "string",
  
"last_used_at": "string",
  
"expires_at": "string",
  
"revoked_at": "string",
  
"revoked_reason": "string",
  
"metadata": {
  
  
"additionalProperties": "string"
  
}
}

Playground​

Authorization
Variables
Key
Value

Samples​

Authentication​

Pillar 2: Key validation and tenant resolution

Operations​

POST/v1/auth/validate

Validate an API key and resolve tenant​

POST
/v1/auth/validate

Internal endpoint used by runtime enforcement layer to validate keys and derive effective tenant.
VALIDATION CHECKS: 1. Key exists in database 2. Key hash matches 3. Status is ACTIVE (not REVOKED or EXPIRED) 4. Current time < expires_at 5. Tenant is ACTIVE (not SUSPENDED or CLOSED)
RESPONSE: - If valid: returns tenant_id, permissions, scope_filter - If invalid: returns valid=false with reason
CACHING: - Results should be cached with short TTL (60s) - Invalidate cache on key revocation

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Request Body​

application/json
JSON
{
  
"key_secret": "string"
}

Responses​

Validation result

application/json
JSON
{
  
"valid": true,
  
"tenant_id": "string",
  
"key_id": "string",
  
"permissions": [
  
  
"string"
  
],
  
"scope_filter": [
  
  
"string"
  
],
  
"expires_at": "string",
  
"reason": "string"
}

Playground​

Authorization
Body

Samples​

Audit​

Pillar 2: Access logging and compliance

Operations​

GET/v1/admin/audit/logs

Query audit logs​

GET
/v1/admin/audit/logs

Returns audit trail of all authenticated operations. Essential for compliance (SOC2, GDPR, etc.).
RETENTION: - Recommended: 90 days hot, 1 year cold storage - Critical for security incident investigation
FILTERING: - By tenant, key, time range, operation, status - Supports complex queries for forensics

Authorizations​

AdminKeyAuth

Administrative API key with full system access

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

Parameters​

Query Parameters

tenant_id
Type
string
key_id
Type
string
operation
Type
string
status
Type
integer
from
Type
string
Format
"date-time"
to
Type
string
Format
"date-time"
cursor
Type
string
limit
Type
integer
Default
50

Responses​

Audit log entries

application/json
JSON
{
  
"logs": [
  
  
{
  
  
  
"log_id": "string",
  
  
  
"timestamp": "string",
  
  
  
"tenant_id": "string",
  
  
  
"key_id": "string",
  
  
  
"user_agent": "string",
  
  
  
"source_ip": "string",
  
  
  
"operation": "string",
  
  
  
"request_id": "string",
  
  
  
"status": 0,
  
  
  
"error_code": "string",
  
  
  
"subject": {
  
  
  
},
  
  
  
"action": {
  
  
  
},
  
  
  
"amount": {
  
  
  
},
  
  
  
"metadata": {
  
  
  
  
"additionalProperties": "string"
  
  
  
}
  
  
}
  
],
  
"next_cursor": "string",
  
"has_more": true
}

Playground​

Authorization
Variables
Key
Value

Samples​

Reservations​

Pillar 3: Runtime budget enforcement (from Cycles v0.1.23)

Operations​

POST/v1/reservationsPOST/v1/reservations/{reservation_id}/commit

Create budget reservation (Cycles v0.1.23)​

POST
/v1/reservations

See Cycles Protocol v0.1.23 specification.
GOVERNANCE INTEGRATION: 1. Validates X-Cycles-API-Key via /v1/auth/validate 2. Derives effective tenant from key 3. Validates Subject.tenant matches effective tenant (403 if mismatch) 4. Checks tenant status (blocks if SUSPENDED or CLOSED) 5. Checks budget ledger exists for scope 6. Applies matching policies (caps, rate limits) 7. Executes Cycles reservation logic (reserve.lua) 8. Logs operation to audit trail

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Responses​

Reservation created (see Cycles v0.1.23)

Playground​

Authorization

Samples​

Commit actual spend (Cycles v0.1.23)​

POST
/v1/reservations/{reservation_id}/commit

See Cycles Protocol v0.1.23 specification.
GOVERNANCE INTEGRATION: - Validates key and tenant as in reservation - Supports ALLOW_WITH_OVERDRAFT policy - Creates debt if overdraft_limit configured - Logs commit to audit trail

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Responses​

Commit succeeded (see Cycles v0.1.23)

Playground​

Authorization

Samples​

Balances​

Pillar 3: Balance queries and monitoring

Operations​

GET/v1/balances

Query budget balances (Cycles v0.1.23)​

GET
/v1/balances

See Cycles Protocol v0.1.23 specification.
GOVERNANCE INTEGRATION: - Returns full ledger state including debt, overdraft_limit, is_over_limit - Scoped to effective tenant - Supports scope filtering via query params

Authorizations​

ApiKeyAuth

Tenant-scoped API key for runtime operations (consistent with Cycles Protocol)

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

Responses​

Balance data (see Cycles v0.1.23)

Playground​

Authorization

Samples​

Powered by VitePress OpenAPI

Released under the Apache 2.0 License.

Copyright 2024-present RunCycles.io