#API reference
Generated from the live API’s OpenAPI spec. Every field below is enforced by the route’s zod schema, so this reference cannot drift. Base URL: https://api.ratifia.com.
Every request carries Authorization: Bearer <token>. Worker takes an org API key, created in the dashboard under API Keys. Decisions takes either an API key or a signed-in dashboard session.
This is the whole integration surface: open a decision, poll it, verify the approval still covers what you are about to do, consume it once, cancel it, reconcile anything left open, and record what actually happened. The API serves other endpoints that the dashboard and the mobile app use; they need a session rather than an API key, and they are not part of this contract.
Try requests interactively in the API explorer, or grab the machine-readable /openapi.json for Postman / Insomnia / codegen. It carries the full nested schemas (e.g. the policy defaults and decision context shapes) that the tables below summarize.
#Decisions
Auth: API key or dashboard session.
#POST /v1/decisions/{id}/evidence
Attach immutable evidence to a decision
Append material the decision is being made ON — a Slack thread, an email, a policy doc. Append-only: evidence is never edited or deleted, and can only be attached while the decision is PENDING. Once it resolves the set is sealed, so what you see is exactly what the approver could see. Re-attaching identical content is a no-op.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
kind | slack_thread | email | document | link | note | yes | |
title | string | no | |
sourceSystem | string | no | |
sourceUrl | string | no | |
sourceRef | object | no | |
body | string | no | |
bodyFormat | text | markdown | no | |
payload | object | no | |
capturedAt | string | no |
#Worker
Auth: API key.
#POST /v1/worker/decisions
Open a HITL decision (decision-first model)
Called by an engine adapter (e.g. flowplane.awaitApproval) to request a human decision for an external-engine run. The policy gate may resolve "not required", in which case approvalNeeded=false and no decision is created.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
engine | bundled | inngest | temporal | trigger | mcp | api | no | |
externalRunId | string | yes | |
stepRef | string | yes | |
workflowRef | string | no | |
approvers | string[] | no | Ad hoc: who may answer. Refused with a policy (the policy decides who). |
approvalsRequired | integer | no | Ad hoc: approvals needed to resolve APPROVED. Default 1; at most the number of approvers; above 1 needs the Team plan. |
timeoutSec | integer | no | Ad hoc: seconds until the decision expires. Refused with a policy (the policy sets it). |
policy | object | no | Policy-driven: the policy key, and optionally the version you built against. A version that is not current is refused with 409 policy_version_mismatch. |
required | boolean | no | Defaults to true. false creates no decision (approvalNeeded: false). |
context | object | no | |
proposedOutput | object | no | |
responseSpec | one of | no | |
docusign | object | no | |
factsHash | string | no |
#GET /v1/worker/decisions
List decisions (API-key scope): the agent's inbox
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
status | query | no | PENDING | APPROVED | REJECTED | EXPIRED | CANCELLED |
limit | query | no | integer |
#GET /v1/worker/decisions/{id}
Get a decision status (API-key scope): poll a park-and-resume verdict
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
#GET /v1/worker/decisions/{id}/verify
Verify an approval before acting on it (API-key scope)
Read-only check that a decision authorizes an action right now: APPROVED, facts hash matches, optional workflow/step match, and not already consumed. Always returns 200 with valid and, when invalid, a reason: not_found, not_approved, facts_mismatch, workflow_mismatch, step_mismatch, or consumed. Use consume to spend the approval.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
factsHash | query | no | string |
workflowRef | query | no | string |
stepRef | query | no | string |
id | path | yes | string |
#POST /v1/worker/decisions/{id}/consume
Consume an approval: authorize exactly one action (API-key scope)
Atomically marks an APPROVED decision as spent by one action. Succeeds once per decision; a retry with the same consumer key returns consumed=true with alreadyConsumed=true, while a different consumer is refused with reason consumed. Refused with the same reasons as verify when the approval does not authorize the action.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
factsHash | string | no | |
workflowRef | string | no | |
stepRef | string | no | |
consumer | string | yes |
#POST /v1/worker/decisions/{id}/cancel
Cancel a pending decision (API-key scope)
Withdraw a decision the agent no longer needs. Only PENDING decisions cancel; an already-resolved one returns cancelled=false with its current status.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
#POST /v1/worker/policies/check
Check that policy keys exist and can reach quorum (API-key scope)
Preflight for CI. For each key: ok, missing, or unsatisfiable (with the reason and any approvers who still need verifying). ok is true only if every key is ok.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
keys | string[] | yes |
#GET /v1/worker/policies
List approval policy keys (API-key scope)
The org's policies, as key + label. For integrations that present a policy picker. Does not include approvers, quorum or surface; use the dashboard for those.