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. All requests are authenticated with Authorization: Bearer <api-key>. Base URL: https://flowplane-api.do.demo.thebuildmill.com.
Decisions
GET /v1/decisions/
List decisions (reviewer inbox)
List decisions for the org, newest first. Filter by status and assignee email for the reviewer inbox.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
status | query | no | PENDING | APPROVED | REJECTED | EXPIRED |
assignee | query | no | string |
limit | query | no | integer |
offset | query | no | integer |
GET /v1/decisions/{id}
Get a decision with its quorum tally
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
POST /v1/decisions/{id}/decide
Approve or reject a decision
Record a vote. Under quorum (FN-82) the decision resolves only when the approval/rejection threshold is met; reject-wins by default. On resolution Flowplane fires the engine resume event.
Parameters:
| Param | In | Required | Type |
|---|---|---|---|
id | path | yes | string |
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
decision | approve | reject | yes | |
note | string | no |
Runs
POST /v1/runs/
Trigger a workflow run
Start a run of a registered workflow. For external engines this fires the engine event and seeds no Flowplane rows; for the bundled engine Flowplane owns the run. Supports idempotency, a per-run timeout, and a cost cap.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
workflowId | string | yes | |
input | object | no | |
idempotencyKey | string | no | |
timeoutSec | integer | no | |
maxCostUsd | number | no |
Worker
POST /v1/worker/register
Register (upsert) a workflow definition
SDK/worker self-registration (FN-34). Idempotent upsert keyed by workflow id for the API key’s org.
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
name | string | no | |
version | integer | no | |
engine | bundled | inngest | temporal | trigger | no | |
steps | object[] | yes |
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 (FN-81) 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 | no | |
externalRunId | string | yes | |
stepRef | string | yes | |
workflowRef | string | no | |
assigneeEmail | string | no | |
policy | string | no | |
required | boolean | no | |
context | object | no | |
timeoutSec | integer | no |
POST /v1/worker/policies
Upsert a named approval policy
Declare an org-scoped approval policy (FN-81/FN-82): a mandatory floor (when a human is required) plus defaults for assignee, approver group, and quorum. Idempotent upsert keyed by (org, name).
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
floor | object[] | no | |
defaults | object | no |