Cycles Protocol API

Interactive reference for the Cycles Protocol endpoints. All requests require an API key passed via the X-Api-Key header.

Getting started with the API?

Deploy the Cycles server or use a running instance
Create a tenant and API key via the Admin API
Make your first Reserve call below

v0.1.25

Cycles Budget Authority API

Download OpenAPI Document

v0 protocol for deterministic budget governance (reserve/commit) with optional decide + balance queries, plus debt/overdraft support with soft-limit reconciliation.

PURPOSE (v0):

Provide a minimal, language-agnostic protocol to enforce deterministic spend exposure for agent runtimes
via concurrency-safe reservations and idempotent commits.
Include optional integration endpoints: /decide (soft landing) and /balances (operator visibility).

NON-GOALS (v0) (NORMATIVE):

Budget establishment and funding operations are out of scope for v0.
v0 defines the reservation/commit/release enforcement plane and balance reporting only.
v0 provides no API for budget CRUD (create/update/delete), allocation setting, credit/deposit, or debit/withdrawal.
Implementations MAY provide these via an operator/admin plane or a separate API; future versions may standardize them.
A reservation lifecycle is denominated in exactly one unit (single-unit reserve/commit/release).
Multi-unit atomic reservation/settlement is a v1+ concern.

AUTH & TENANCY (NORMATIVE):

Requests are authenticated via X-Cycles-API-Key.
Server determines an "effective tenant" from the API key (or other auth context).
Subject.tenant is a budgeting dimension and MUST be validated against the effective tenant.
If mismatched, server MUST return 403 FORBIDDEN.
Reservation ownership MUST be enforced: every reservation is bound to the effective tenant at creation.
Any subsequent GET/commit/release for a reservation that exists but is owned by a different tenant
MUST return 403 FORBIDDEN.
Balance visibility MUST be tenant-scoped: the server MUST only return balances within the effective tenant.
If a request attempts to query another tenant (e.g., tenant filter mismatches), server MUST return 403 FORBIDDEN.

EVOLUTION CONTRACT:

This API starts at v0.1.0 with /v1 paths to avoid future client churn.
v1+ evolution MUST be backward-compatible by default: new fields are additive, existing field meanings MUST NOT change.
Breaking changes (e.g., new required fields, semantic changes) require a new major API path (e.g., /v2).

CORE INVARIANTS:

Reserve is atomic across all derived scopes.
Commit and release are idempotent.
No double-charge on retries (idempotency key enforced).

ERROR SEMANTICS (NORMATIVE):

Budget denials MUST return HTTP 409 with error=BUDGET_EXCEEDED.
Overdraft limit exceeded MUST return HTTP 409 with error=OVERDRAFT_LIMIT_EXCEEDED in two cases:
1. During commit: when overage_policy=ALLOW_WITH_OVERDRAFT and (current_debt + delta) > overdraft_limit at commit time
2. During reservation: when the scope is in over-limit state (debt > overdraft_limit due to prior concurrent commits)
Outstanding debt blocking reservation MUST return HTTP 409 with error=DEBT_OUTSTANDING
(when debt > 0 and new reservation is attempted).
Finalized reservations MUST return HTTP 409 with error=RESERVATION_FINALIZED.
Expired reservations MUST return HTTP 410 with error=RESERVATION_EXPIRED.
(commit/release: beyond expires_at_ms + grace_period_ms; extend: beyond expires_at_ms).
Reservations that never existed MUST return HTTP 404 with error=NOT_FOUND.
HTTP 429 is reserved for server-side throttling/rate limiting (optional in v0), not deterministic budget exhaustion.
Unit mismatch MUST return HTTP 400 with error=UNIT_MISMATCH in any of these cases:
(a) reserve — estimate.unit does not match any budget stored for the derived scopes,
but at least one of those scopes has a budget in a different unit;
(b) commit — actual.unit differs from the reservation's estimate.unit;
(c) event — actual.unit does not match the budget stored for the target scope;
(d) decide — estimate.unit does not match any budget stored for the derived scopes,
but at least one of those scopes has a budget in a different unit. This is an
exception to /decide's general "return decision=DENY (200) without 4xx" pattern,
which applies only to budget-state conditions (debt, overdraft, insufficient
remaining), not request-validity errors like a wrong unit.
When the cause is a wrong unit (rather than the absence of any budget at the scope),
servers SHOULD populate the error response's details object with:
- scope — the canonical scope identifier where the mismatch was detected
- requested_unit — the unit supplied by the client
- expected_units — array of units for which a budget does exist at that scope
  so clients can self-correct without a separate lookup. HTTP 404 with error=NOT_FOUND
  is reserved for the case where the target scope has no budget in ANY unit (the
  runtime plane uses the single NOT_FOUND code for all resource-not-found conditions;
  the message field carries the specific reason, e.g. "Budget not found for provided
  scope: ...").
For expiry comparisons, “now” refers to server time (not client-provided time).
When is_over_limit=true, server MUST return 409 OVERDRAFT_LIMIT_EXCEEDED for new reservations.
This takes precedence over DEBT_OUTSTANDING even when debt > 0.

OVERDRAFT RECONCILIATION (NORMATIVE):

When concurrent commits cause debt > overdraft_limit on a scope, the server MUST mark that scope as "over-limit" (is_over_limit=true).
Over-limit scopes MUST reject ALL new reservation attempts with 409 OVERDRAFT_LIMIT_EXCEEDED until debt is reduced below overdraft_limit.
Operators reconcile over-limit scopes via budget funding operations (out-of-scope for this API).
When debt is repaid below overdraft_limit, is_over_limit automatically returns to false.
Servers SHOULD provide monitoring/alerting when scopes enter over-limit state:
- Log events with scope identifier, current debt, and overdraft_limit
- Optionally emit webhooks or notifications to operators
- Optionally expose metrics endpoint showing over-limit scope count
Clients SHOULD handle 409 OVERDRAFT_LIMIT_EXCEEDED on reservation as a signal to wait/retry with exponential backoff, or escalate to operators.

IDEMPOTENCY (NORMATIVE):

If X-Idempotency-Key header is present and body.idempotency_key is present, they MUST match.
Server MUST enforce idempotency per (effective tenant, endpoint, idempotency_key).
On replay of an idempotent request that previously succeeded, server MUST return the original successful
response payload (including any server-generated identifiers such as reservation_id).
If the same key is reused with a different request payload, server MUST return 409 IDEMPOTENCY_MISMATCH.
Servers SHOULD compare idempotency payloads using a canonical JSON representation
(e.g., RFC 8785 JSON Canonicalization Scheme) or an equivalent stable serialization.

SCOPE DERIVATION (NORMATIVE):

Server derives canonical scope identifiers and a canonical scope_path from Subject fields.
Canonical ordering is: tenant → workspace → app → workflow → agent → toolset.
Only explicitly provided subject levels are included in scope paths; intermediate gaps are skipped (not filled with "default").
Scopes without budgets are skipped during enforcement; at least one derived scope MUST have a budget.
affected_scopes returned by the server MUST be in that canonical order.

RESERVATION LEASING (GUIDANCE):

To mitigate "zombie reservations" (client crash after reserve), SDKs SHOULD:
- keep ttl_ms short (typically 10s–30s),
- include modest estimation buffers when using overage_policy=REJECT,
- reserve in small initial leases and increase gradually ("slow start") for long or bursty operations,
- prefer chunked reserve/commit cycles for long-running actions rather than a single large reservation.

OVERDRAFT MONITORING (GUIDANCE):

Implementations SHOULD provide visibility into over-limit states:
- Dashboard showing scopes with is_over_limit=true
- Alerts when debt exceeds overdraft_limit
- Time-series metrics: debt_utilization = debt / overdraft_limit
Recommended alerting thresholds:
- Warning at 80% of overdraft_limit
- Critical at 100% (over-limit state)
Recommended operator runbook:
1. Investigate which reservations caused the over-limit state
2. Determine if overdraft_limit should be increased (normal variance) or if this represents anomalous consumption (incident)
3. Fund the scope to repay debt below limit
4. Monitor that is_over_limit returns to false
5. Resume operations automatically

CORRELATION AND TRACING (NORMATIVE, cross-plane):
This section defines the cross-surface correlation contract for the entire Cycles
spec family. It is normative for every Cycles server operation on every plane
(runtime, governance-admin, action-kinds, and any extension that layers onto
these bases). Companion specs SHOULD carry a brief pointer to this section and
MUST NOT restate a conflicting contract.

Three-tier correlation model:
* request_id — one HTTP request grain. Set by the server. Echoed on
X-Request-Id response header, on ErrorResponse, and on every event / audit
entry that is causally downstream of the request (including entries emitted
from queued or deferred work spawned by the request).
* trace_id — logical-operation grain. W3C Trace Context-compatible. Accepted
from inbound headers or generated by the server. Echoed on X-Cycles-Trace-Id
response header and propagated to events, audit entries, and outbound
webhook deliveries.
* correlation_id — event-stream cluster grain. Set by the server as a
deterministic hash over (tenant_id, scope, action_kind_or_risk_class,
window, window_key) to JOIN threshold-alert → trip → reset chains and
observed_denied ↔ reservation.denied pairs. Scoped to the event stream only.

Inbound header precedence (server extracts trace_id by the first matching rule):
1. traceparent header, if present AND parses as a valid W3C Trace Context
value (version 00, non-all-zero trace-id, non-all-zero span-id) → use its
trace-id (the leftmost 32-hex segment).
2. Else X-Cycles-Trace-Id header, if present AND matches ^[0-9a-f]{32}$
AND is not all-zero → use its value directly.
3. Else server generates a new trace_id: 16 random bytes encoded as 32
lowercase hex characters. The all-zero value is invalid per W3C Trace
Context §3.2.2.3 and MUST be re-rolled.

Header validation and precedence rules:
* A malformed traceparent OR malformed X-Cycles-Trace-Id MUST be treated
as absent for that header; the server falls through to the next rule. The
server MUST NOT reject a request for a malformed correlation header.
* If both traceparent and X-Cycles-Trace-Id are present, both valid, but
their trace-ids DISAGREE, traceparent wins (OpenTelemetry interop takes
precedence over the flat convenience header). The server MAY log this
condition for diagnostics but MUST NOT reject the request.

Outbound response contract (every plane, every response):
* Servers MUST echo X-Cycles-Trace-Id on every response (2xx, 4xx, 5xx).
The header is declared as X-Cycles-Trace-Id in this document's
components.headers and re-declared in the companion spec's own
components.headers for OpenAPI tooling conformance.
* ErrorResponse bodies MUST carry trace_id on every conformant error.
* Events and audit-log entries causally downstream of the request MUST
carry trace_id. See each companion spec's Event / AuditLogEntry schema.

Propagation contract:
* The server propagates trace_id onto: the audit-log entry for the request
(one per authenticated request that hits the governance plane), every
event emitted as a side effect of the request (runtime or governance),
and every outbound webhook delivery. Propagation across thread, queue, or
process boundaries is REQUIRED; loss at the request-thread boundary is
non-compliant.
* Outbound webhook deliveries carry X-Cycles-Trace-Id AND traceparent
headers constructed as documented in the WEBHOOK EVENT GUIDANCE section
below (including the trace-flags preservation rule).

Format: ^[0-9a-f]{32}$ — 32 lowercase hex characters (128-bit trace ID).

Backward compatibility:
* trace_id is declared as an OPTIONAL property on ErrorResponse, Event,
and AuditLogEntry schemas (no wire-contract break). Servers conformant
with this section MUST populate it; clients MUST tolerate its absence on
entries emitted by older servers.
* Adding X-Cycles-Trace-Id as a response header is additive; clients that
do not read the header are unaffected.
* Accepting traceparent / X-Cycles-Trace-Id as inbound request headers
is additive; clients that do not send them are unaffected.

WEBHOOK EVENT GUIDANCE (GUIDANCE):
Implementations MAY emit webhook events when runtime operations produce observable state changes.
This enables operators and tenant applications to react to budget state transitions in real-time
without polling. The webhook delivery system is separate from the protocol endpoints — it does not
add new API paths to the runtime server.

Event types emitted by the runtime server:
* reservation.denied — Reserve or decide returned DENY (budget exceeded, overdraft limit, frozen, etc.)
* reservation.commit_overage — Commit actual amount exceeded estimated amount
* reservation.expired — Reservation TTL expired without commit or release (via background sweeper)
* budget.exhausted — Remaining budget reached 0 after a reservation or event
* budget.debt_incurred — Commit created new debt via ALLOW_WITH_OVERDRAFT policy
* budget.over_limit_entered — is_over_limit flipped to true (debt > overdraft_limit)
* budget.over_limit_exited — Debt repaid below overdraft_limit (via admin funding operations)
* budget.threshold_crossed — Utilization crossed a configured threshold (e.g., 80%, 95%)
* budget.burn_rate_anomaly — Spend rate exceeded baseline by configured multiplier

Event types emitted by the admin/operator server:
* tenant.created/updated/suspended/reactivated/closed — Tenant lifecycle
* budget.created/updated/funded/debited/reset/debt_repaid/frozen/unfrozen/closed — Budget lifecycle
* api_key.created/revoked/expired/permissions_changed/auth_failed — API key lifecycle
* policy.created/updated/deleted — Policy lifecycle
* system.store_connection_lost/restored, system.high_latency — System health
* system.webhook_delivery_failed — Meta-alert for persistent delivery failures

Standard event payload schema (JSON):
* event_id (string, required) — Globally unique (e.g., "evt_01abc..."). Use for deduplication.
* event_type (string, required) — Dotted format: "{category}.{action}" (e.g., "reservation.denied")
* category (string, required) — One of: budget, reservation, tenant, api_key, policy, system
* timestamp (string, date-time, required) — ISO 8601 UTC
* tenant_id (string, required) — Tenant context. System events use "system".
* scope (string, optional) — Full scope path affected (e.g., "tenant:acme/agent:bot")
* actor (object, optional) — Who caused the event: { type: admin|api_key|system|scheduler, key_id?, source_ip? }
* source (string, required) — Service that emitted: "cycles-server", "cycles-admin", "expiry-sweeper"
* data (object, optional) — Event-specific payload (varies by event_type)
* correlation_id (string, optional) — Links related events for chain reconstruction
* request_id (string, optional) — X-Request-Id from the originating HTTP request.
MUST be populated on every event causally downstream of an HTTP request,
including events emitted from queued, deferred, or otherwise-async work spawned
by that request. MAY be absent on internal sweeper/expiry-generated events that
have no originating HTTP request. See CORRELATION AND TRACING section below.
* trace_id (string, optional, pattern ^[0-9a-f]{32}$) — W3C Trace Context trace-id
for the logical operation. Populated on every event produced by a server that
conforms to the CORRELATION AND TRACING contract below.
* metadata (object, optional) — Operator-defined key-value pairs

Webhook delivery protocol:
* Delivery method: HTTP POST to subscriber's URL with JSON event payload as body
* Delivery semantics: At-least-once. Consumers MUST deduplicate using event_id.
* Ordering: Events for the same tenant are dispatched in order. Cross-tenant ordering NOT guaranteed.
* Non-blocking: Webhook delivery MUST NOT block the operation that produced the event.

Required HTTP headers on webhook delivery:
* Content-Type: application/json
* X-Cycles-Event-Id: {event_id} — For deduplication
* X-Cycles-Event-Type: {event_type} — For routing
* X-Cycles-Signature: sha256={hex} — HMAC-SHA256 of raw request body using subscription's signing secret
* X-Cycles-Trace-Id: {trace_id} — W3C Trace Context trace-id (32-hex) for the
logical operation that produced this event. Always required; the server always
has a trace_id per the CORRELATION AND TRACING fallback-generate rule.
* traceparent: 00-{trace_id}-{fresh-span-id-16-hex}-{trace-flags} — W3C Trace
Context version 00 header. Always required. trace_id MUST equal the value in
X-Cycles-Trace-Id. span-id MUST be freshly generated for the outbound delivery
(NOT reused from inbound). trace-flags rules:
- If the inbound request to Cycles carried a valid traceparent, the server
MUST preserve the inbound trace-flags byte on the outbound traceparent
(so a sampled=0 upstream is not silently flipped to sampled=1).
- If the trace was derived from X-Cycles-Trace-Id (no inbound W3C
traceparent) OR generated fresh by the server, the server uses a default
trace-flags value of 01 (sampled).
The trace_id field also appears in the event envelope body so subscribers
unfamiliar with W3C Trace Context can still correlate via the JSON payload.
* User-Agent: {service-name}/{version}
* Custom headers from subscription configuration (e.g., Authorization)

Signature verification (X-Cycles-Signature):
* Algorithm: HMAC-SHA256
* Input: Raw JSON request body (bytes, not parsed)
* Key: Subscription's signing_secret (UTF-8 encoded)
* Format: "sha256=" + lowercase hex encoding of HMAC digest
* Consumers SHOULD verify the signature before processing the event.
* Use constant-time comparison (e.g., hmac.compare_digest) to prevent timing attacks.

Retry and failure handling:
* On non-2xx response: exponential backoff retry (default: 5 retries, 1s/2s/4s/8s/16s, max 60s)
* After all retries exhausted: delivery marked FAILED, system.webhook_delivery_failed event emitted
* After N consecutive failures (default 10): subscription auto-disabled (status → DISABLED)
* Disabled subscriptions can be re-enabled via admin API (resets failure counter)

Retention:
* Event records: 90 days hot storage (recommended). TTL enforced via Redis EXPIRE.
* Delivery records: 14 days (operational debugging data).
* ZSET index entries: Trimmed hourly by background cleanup job.
* Stale deliveries: Deliveries older than 24h (configurable) are auto-failed on pickup
to prevent delivering ancient webhooks after prolonged service outage.

Extensibility:
* New event types MAY be added in future versions without a breaking change.
* Consumers MUST ignore unrecognized event types gracefully.
* Custom event types MUST use a "custom." prefix (e.g., "custom.billing.invoice_sent").

License

Apache 2.0

Servers

https://api.cycles.localReplace with your implementation endpoint

Cycles Protocol API ​

Cycles Budget Authority API​

License​

Servers​

Decisions​

Operations​

Optional preflight policy decision (no reservation created)​

Authorizations​

Parameters​

Header Parameters

Request Body​

Responses​

Playground​

Samples​

Reservations​

Operations​

List reservations (optional recovery/debug endpoint)​

Authorizations​

Parameters​

Query Parameters

Responses​

Playground​

Samples​

Reserve budget for a planned action (concurrency-safe)​

Authorizations​

Parameters​

Header Parameters

Request Body​

Responses​

Playground​

Samples​

Get reservation details (optional, for debugging)​

Authorizations​

Parameters​

Path Parameters

Responses​

Playground​

Samples​

Commit actual spend for a reservation (auto-releases delta)​

Authorizations​

Parameters​

Header Parameters

Path Parameters

Request Body​

Responses​

Playground​

Samples​

Release an unused reservation​

Authorizations​

Parameters​

Header Parameters

Path Parameters

Request Body​

Responses​

Playground​

Samples​

Extend reservation TTL (lease refresh / heartbeat)​

Authorizations​

Parameters​

Header Parameters

Path Parameters

Request Body​

Responses​

Playground​

Samples​

Balances​

Operations​

Query current budget balances across scopes (nice-to-have)​

Authorizations​

Parameters​

Query Parameters

Responses​

Playground​

Samples​

Events​

Operations​

Optional post-only accounting when pre-estimation is not available​

Authorizations​

Parameters​

Header Parameters

Cycles Protocol API

Cycles Budget Authority API

License

Servers

Decisions

Operations

Optional preflight policy decision (no reservation created)

Authorizations

Parameters

Request Body

Responses

Playground

Samples

Reservations

Operations

List reservations (optional recovery/debug endpoint)

Authorizations

Parameters

Responses

Playground

Samples

Reserve budget for a planned action (concurrency-safe)

Authorizations

Parameters

Request Body

Responses

Playground

Samples

Get reservation details (optional, for debugging)

Authorizations

Parameters

Responses

Playground

Samples

Commit actual spend for a reservation (auto-releases delta)

Authorizations

Parameters

Request Body

Responses

Playground

Samples

Release an unused reservation

Authorizations

Parameters

Request Body

Responses

Playground

Samples

Extend reservation TTL (lease refresh / heartbeat)

Authorizations

Parameters

Request Body

Responses

Playground

Samples

Balances

Operations

Query current budget balances across scopes (nice-to-have)

Authorizations

Parameters

Responses

Playground

Samples

Events

Operations

Optional post-only accounting when pre-estimation is not available

Authorizations

Parameters

Request Body

Responses

Playground

Samples