Ask permission to perform a side effect
The gate. Returns a decision that tells the caller whether to perform the action, replay a recorded result, wait, or stop. Call this immediately BEFORE the side effect, and report the outcome immediately after.
Request
- Base URL: https://ratchetgate.com
- URL: https://ratchetgate.com/v1/effects/begin
- Auth: HTTP bearer
Request body
Namespaced kind of side effect, e.g. "email.send" or "payment.charge". Policy is configured per type.
Stable identifier for this logical action. Derive it from the work itself (e.g. a hash of recipient + template + period), never from a random value or a timestamp.
Declared external cost of this effect in micro-USD (1e-6 USD). SEND THIS. Budget ceilings are computed from it, and a ceiling with nothing declared against it never triggers — the spend limit you configured would be silently inert. It is also what makes the prevented-loss figure meaningful. Ratchet never collects this money; it only counts it.
Which agent is acting. For operator visibility.
Groups effects belonging to one agent run.
Small, non-sensitive metadata shown in the console. Redact secrets before sending.
Axes this effect can be counted against, most usefully the counterparty: {"counterparty":"acct_1234"}. Send the identifier itself — only a keyed hash is stored, so Ratchet can count how much has gone to a destination today without ever being able to say which destination it is. A declaration can only TIGHTEN: it adds whatever ceiling policy keys on that dimension, and never removes the workspace, key or effect-type ceilings. Omitting one that policy requires is refused with dimension_required.
Requested lease length. Clamped to the policy maximum for this effect type.
Which vendor performs this effect (e.g. "stripe", "square", "adyen"). Shapes the vendor_idempotency_key returned with an execute decision so it satisfies that vendor's length and placement rules.
Declares this effect part of a unit of work that can be rolled back as a whole. Use one stable key per logical workflow, e.g. "booking:trip_8812".
Set when THIS effect is the compensation for another. Reporting it succeeded marks the original reversed.
Response
Default Response
execute: you hold the lease, perform the effect. duplicate: already done, replay result, do NOT perform it. in_flight: another caller holds a live lease. blocked: a prior attempt's real-world outcome is unknown. approval_required: an operator must approve first. denied: policy, budget, or a rejected approval refused it.
Present only when decision is "execute". Required to report the outcome.
Present when a spend ceiling is configured for this effect type but this call declared no cost, so nothing counted toward it. The ceiling cannot trigger until callers send estimated_cost_micros.
Present when this workspace has never reported an outcome and unreported effects are accumulating. Every begin must be followed by POST /v1/effects/{effect_id}/report. Unreported effects become "indeterminate" when their lease expires, and the next attempt on the same idempotency_key is then blocked until an operator resolves it.
Changes
No recorded changes to this operation across all 1 revision of this API.