Flow API: processes, approvals and external events
A process in Flow is a long-running scenario made of steps: get approval, wait, wait for an event from an external system, perform an action, branch. A process can run for hours or days, survives server restarts and never loses steps. This article covers the processes API: definitions and their versions, starting processes and instances, approvals and receiving external events.
General rules — the base URL, keys, the X-Workspace-Id and Idempotency-Key headers, the error format — are described in Flow API: basics. To see how processes look in the interface, read Flow: processes and approvals.
How it works
An administrator creates a process definition: a key, a name, an object type and steps. The steps live in a version: first a draft, then it is published.
A process is started via the API, with an action button on an object card, or with the
start_processautomation action. Starting creates an instance on the current published version.Steps run in the background on behalf of the process's execution principal. Waits are database records, not server memory: a restart neither loses nor repeats steps.
An
approvalstep creates an approval; the assignees decide it viaPOST /approvals/{id}/decision.A
wait_eventstep waits for an external event; your system sends it toPOST /events.
An instance runs on its own version to the end: publishing a new version doesn't change processes already in progress.
All methods
Method | Request | Permission |
|---|---|---|
List processes |
|
|
Create a process |
|
|
Process with its current and draft versions |
|
|
New draft |
|
|
Read a version |
|
|
Replace a draft's steps |
|
|
Publish a draft |
|
|
Start |
|
|
List instances |
|
|
Full instance |
|
|
Cancel an instance |
|
|
My approvals |
| assignee |
My approvals across all workspaces |
| person's session only, assignee |
Approval |
| assignee or |
Decision |
| assignee |
Ingest an external event |
|
|
Paths are relative to https://flow.sensever.com/v1. You can pass a process's id instead of its {key}. Process permissions are checked on its object type; for a process without a type, on the workspace.
Process definition
Create a process
POST /processes creates a definition and draft version 1. A draft is validated only on publishing, so you can save an unfinished graph too.
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Process key: |
| string | yes | Name, 1–200 characters |
| string or null | no | Key or id of the object type. Without it the process runs without an object |
| uuid | yes | On whose behalf the steps run. This is you or an active service principal; only a holder of |
| string | yes | Key of the first step |
| object | yes | Steps by key, no more than 100 |
The list of service principals that can execute scenarios is returned by GET /object-types/{type}/automations in the execution_principals field (it is empty without the automation.manage permission).
curl -s https://flow.sensever.com/v1/processes \
-H "Authorization: Bearer $FLOW_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-discount-approval-1" \
-d @discount_approval.jsonThe file discount_approval.json is a process that approves a discount on a deal and then waits for payment from the accounting system:
{
"key": "discount_approval",
"name": "Discount approval",
"object_type": "deal",
"execution_principal_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b74",
"start": "approve",
"steps": {
"approve": {
"type": "approval",
"title": "Approve the discount on this deal",
"assignees": [{"role": "admin"}],
"policy": {"mode": "any"},
"timeout": "P2D",
"on_approved": "wait_payment",
"on_rejected": "rejected",
"on_timeout": "escalate"
},
"escalate": {
"type": "escalate",
"notify": {"object": "owner"},
"title": "Discount not approved within two days",
"next": "rejected"
},
"wait_payment": {
"type": "wait_event",
"event_type": "erp.payment_received",
"correlation": "object.id",
"timeout": "P14D",
"on_event": "done",
"on_timeout": "rejected"
},
"done": {"type": "complete"},
"rejected": {"type": "fail", "code": "DISCOUNT_REJECTED", "message": "Discount not approved"}
}
}The 201 response is a Process object: id, key, name, object_type_id, object_type, execution_principal_id, current_version_id (null for now), draft_version_id, current_version, draft_version, created_at, archived_at.
Steps
Each step is an object with a type field and the parameters of its kind. A step key is ^[a-z][a-z0-9_]{0,62}$. The next, on_* and default parameters name the next step.
| Parameters | What it does |
|---|---|---|
|
| Performs an automation action on the instance's object (same shape as in automations, except |
|
| Pause: an ISO 8601 duration, for example |
|
| Waits until the moment given by an expression (date or time). A moment in the past moves on immediately |
|
| Waits for an external event of this type with the correlation key from the |
|
| Creates an approval and waits for a decision |
|
| Takes the first branch whose |
|
| Starts 2–20 branches at once |
|
| Waits for all branches (or |
|
| Sends a notification to Sensever chat |
| — | Finishes the instance with status |
|
| Fails the instance: |
on_timeout is set only together with timeout. action steps with call_webhook, send_notification and send_email and the escalate step are external: they run "at least once" and are retried with a delay of min(2^n·5 s, 10 min) ±20%; the fifth failure is final. The recipient gets the idempotency key p:<instance_id>:<token_id> — for a webhook, in the Idempotency-Key header.
Loop protection: no more than 1000 step visits per instance.
Approval assignees
assignees is a list of the elements below or a single {"expr": "…"} object. After roles and fields are expanded, the result must be 1 to 50 active people.
Element | Who |
|---|---|
| Principal by id |
| Everyone with the system role: |
| Everyone with a custom workspace role |
| People from an object field of type |
| The object's assignee; |
| An expression that yields an id or a list of ids |
policy.mode: any — one "approved" is enough, all — everyone must approve, quorum — quorum approvals are needed. Recipients of notify in escalate are set the same way as for the send_notification action: id, {"role"}, {"role_id"}, {"field"}, {"object"}.
Expressions in steps
until, correlation, branches[].when and assignees.expr are expressions in process mode. They have access to the instance's object (object.id, object.<field>), the start input context.input, the results of completed steps context.steps.<step>.outcome and context.steps.<step>.result, and context.instance_id. A process without a type has no object. The syntax is described in Flow API: automations, reminders and expressions.
Versions and publishing
POST /processes/{key}/versionswith a{start, steps}body creates the next draft. A process has only one draft: a second one returns422 VALIDATION_FAILEDwithdetails.reason = draft_exists.PATCH /process-versions/{id}with the same body replaces the draft's steps entirely. A published or retired version returns409 DEFINITION_IMMUTABLE.POST /process-versions/{id}/publishwith no body validates the graph, compiles expressions, and checks actions, assignees and the execution principal.
Publishing collects all errors at once: 422 DEFINITION_INVALID with details.errors[{path, code, message}], where path looks like steps.<step>.<parameter>. Unreachable steps and a join without parallel are warnings; they don't block publishing. After publishing, the previous current version becomes retired, and running instances stay on theirs.
A successful response is a ProcessPublication: {"version": {…}, "warnings": [{path, code, message}]}. Version statuses are draft, published, retired. A version document can be up to 48 KB.
Definition commands accept Prefer: return=minimal: instead of the full object you get a short result with id, status and href for the next GET, and for publishing also definition_id, the first 50 warnings and warnings_total. Learn more in Flow API: types, fields, statuses and publishing.
Starting and instances
Start a process
POST /processes/{key}/start creates an instance of the current published version. The Idempotency-Key header is required.
Field | Type | Required | Description |
|---|---|---|---|
| uuid or null | for a process with a type | An object of this type that you can read. A process without a type doesn't accept an object |
| object | no | Instance input, available in expressions as |
| string or null | no | Idempotent start key, 1–255 bytes: one instance per key in the workspace |
curl -s https://flow.sensever.com/v1/processes/discount_approval/start \
-H "Authorization: Bearer $FLOW_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: start-deal-7f3a-1" \
-d '{"object_id":"0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72","input":{"discount":15},"start_key":"deal-7f3a-discount"}'The 201 response is the new instance. With a start_key that has already started an instance, the response is 200 and the same instance. Idempotency-Key protects against a repeated HTTP request for 24 hours, while start_key protects against a second instance forever: for example, one process per deal.
Steps run in the background, so the tokens, waits and approvals lists in the start response are empty. Track progress via GET /process-instances/{id} or the process.* webhooks.
Start errors:
HTTP |
| When |
|---|---|---|
404 |
| The process doesn't exist, is archived, or you can't see it. With |
404 |
| The object doesn't exist or you can't read it |
409 |
| The object is archived |
422 |
| No |
403 |
| No |
Instance
Field | Description |
|---|---|
| Instance id |
|
|
| The version the instance runs on |
| The object or |
|
|
| Start input |
| Results of completed steps: |
| The instance's version number, grows with each step |
| Start key or |
| End-to-end id of the event chain |
|
|
| Failure error ( |
| Timestamps |
| Execution positions in the graph: |
| Event waits: |
| The instance's approvals |
A step's outcome is one of succeeded, elapsed, event, timeout, approved, rejected, branch.<i>, default, parallel, arrived, joined, passed, failed, completed. Each step visit is a new token, so tokens shows the entire path history.
List instances
GET /process-instances returns instances of processes visible to you, newest first, paginated (page[size] 1–200, default 50, and page[cursor]).
Parameter | Description |
|---|---|
| Only instances of this object |
| Only this process (key or id). An unknown or invisible process yields an empty page |
|
|
In the list, tokens, waits and approvals are empty — GET /process-instances/{id} gives the full picture.
Cancel an instance
POST /process-instances/{id}/cancel with no body. A running instance becomes cancelled with error: {code: PROCESS_CANCELLED, cause: api}; its tokens, waits, approvals and timers are cancelled. A finished instance is returned unchanged with code 200.
Archiving an object cancels all its running instances (cause: object_archived). Restoring the object doesn't resume cancelled processes.
Approvals
My approvals
GET /approvals returns approvals assigned to you, newest first, no more than 200.
Parameter | Values |
|---|---|
| Only |
|
|
Approval (Approval):
Field | Description |
|---|---|
| Ids of the approval, the instance and the step token |
| Step and process |
| Title from the step |
| The instance's object or |
|
|
|
|
| Timestamps |
| Assignees: |
GET /approvals/{id} is visible to the assignees and everyone who can read the process.
Approvals across all workspaces
GET /me/approvals returns approvals assigned to a person across all workspaces where they are an active member at once. This is the "Approvals" item in "All workspaces" mode. The method works only with a person's browser session or a Sensever embed token; X-Workspace-Id isn't needed. An API key gets 401: a key belongs to its own workspaces, so an integration reads GET /approvals in each workspace separately.
Parameter | Values |
|---|---|
|
|
| Only this workspace (id from |
| 1–100, default 50 |
|
|
In each workspace the selection is the same as GET /approvals?assigned_to=me there. Order: newest first. A response item:
Field | Description |
|---|---|
| The approval ( |
| Workspace: |
| The person's member in this workspace — its id appears in |
|
|
| Assignee names by |
meta.pending_count is how many approvals await the person's decision across all workspaces read, regardless of status and page (the counter in the left column). meta.workspaces_scanned, meta.skipped_workspaces and meta.partial work as in POST /me/objects/query: no more than 50 workspaces are read per page, and a time budget applies.
The decision is a regular POST /approvals/{id}/decision with X-Workspace-Id = the item's workspace.id.
Decision
POST /approvals/{id}/decision:
Field | Type | Required | Description |
|---|---|---|---|
| string | yes |
|
| string or null | no | Comment, up to 1000 bytes |
{"decision": "approved", "comment": "Approved until the end of the quarter"}The response is the approval after the decision. Once the policy reaches a decision, the approval becomes approved or rejected, and the process moves on in the background.
HTTP |
| When |
|---|---|---|
422 |
| You aren't assigned to this approval |
409 |
| You've already decided, or the approval is closed |
404 |
| The approval doesn't exist, or you can't see it |
Assignees get a direct message in Sensever chat from "Sensever Flow", and if the person has enabled the email channel and the approvals category in email_categories, an email as well. It can be turned off in personal notification settings (category approvals, "Approvals and processes"). If the approval is already decided or closed by the time of delivery, the message isn't sent.
External events
POST /events accepts an event from your system: a payment from an ERP, a signed contract, a customer reply. The event advances wait_event steps and triggers automations with the external.event trigger. The Idempotency-Key header is required.
Field | Type | Required | Description |
|---|---|---|---|
| string | yes | Source key: |
| string | yes | Event id in the source, 1–255 characters. Together with |
| string | yes | Type: lowercase segments separated by dots, for example |
| string | yes | Correlation key, 1–512 characters. Matches |
| object | yes | Event body, up to 256 KB. Stored for 90 days |
| string or null | no | Event time in the source (RFC 3339) |
| integer | no | Version of your event's shape, 1–32767, default 1 |
curl -s https://flow.sensever.com/v1/events \
-H "Authorization: Bearer $FLOW_KEY" \
-H "X-Workspace-Id: $WORKSPACE_ID" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: erp-pay-100500" \
-d '{
"source": "erp",
"external_event_id": "pay-100500",
"event_type": "erp.payment_received",
"correlation_key": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b72",
"payload": {"amount": "120000.00", "currency": "RUB"},
"occurred_at": "2026-09-25T09:15:00Z"
}'Response:
{
"event_id": "0190f3c2-7d4e-7a31-9b1f-5c2d8e4a6b80",
"duplicate": false,
"received_at": "2026-09-25T09:15:01.204518Z",
"resolved_waits": 1
}resolved_waits is how many process waits this request resolved.
Identity and retries
An event is identified by the pair (source, external_event_id):
First receipt —
202: the event is stored,wait_eventwaits with the sameevent_typeandcorrelation_keyare resolved, andexternal.event_receivedis published.Retry with the same content —
200,duplicate: true, the originalevent_id. Nothing advances a second time;resolved_waitsis 0.Same id with different content —
422 EXTERNAL_EVENT_CONFLICT:event_type,correlation_keyorpayloaddiffers (compared by value).detailscontainssource,external_event_idand theevent_idof the already accepted event.
EXTERNAL_EVENT_CONFLICT means a bug in the integration: one id in the source was given to two different events, or the event changed after it was sent. Don't retry such a request. If the event really is new, give it a new external_event_id; if an old one was corrected, Flow has already accounted for the first version, and a retry won't change it.
Idempotency-Key and external_event_id complement each other. Retrying an HTTP request with the same key and body returns the stored response byte for byte (header Idempotency-Replayed: true). A retry with a new key but the same event returns 200 duplicate. A convenient choice for the key is the same external_event_id.
Event before the wait
An event can arrive before the process reaches the wait_event step: for example, the payment came in while the discount is still being approved. If an event with the matching event_type and correlation_key was accepted after the instance started and hasn't resolved its waits yet, the wait_event step resolves immediately as soon as the instance reaches it.
Other errors
HTTP |
| When |
|---|---|---|
413 |
|
|
422 |
| Invalid field format or missing |
403 |
| No |
There is no registry of allowed event types per source: any event_type in the correct format is accepted.
Process webhooks
Instances and approvals publish events you can subscribe to (see Flow API: webhooks):
Event | When |
|---|---|
| A process version was published |
| An instance was started |
| A step was completed: |
| An instance finished |
| An approval was created, a decision was made |
| An external event was accepted |
Automations can react to the same events with the process.event and external.event triggers, and start processes with the start_process action.
Reliability
A step is one transaction. Internal actions on an object run exactly once; external ones (
call_webhook,send_notification,send_email,escalate) run at least once, with an idempotency key for the recipient.Pauses and timeouts are database timers with scheduler precision of about 5 seconds. Server restarts, including in the middle of a step, don't lose waits.
An approval decision or an accepted event doesn't advance the process within the request itself: it marks the wait, and a background queue continues the step. So right after the response the instance may still show the previous step — re-read it a second or two later or wait for
process.step_completed.
Comentários