Flow API: processes, approvals and external events

SENSEVER

The official Sensever channel: guides and API documentation for Chat, Requests, Flow, Studio, bots and messaging channels.

17 min czytania

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

  1. 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.

  2. A process is started via the API, with an action button on an object card, or with the start_process automation action. Starting creates an instance on the current published version.

  3. 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.

  4. An approval step creates an approval; the assignees decide it via POST /approvals/{id}/decision.

  5. A wait_event step waits for an external event; your system sends it to POST /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

GET /processes

process.read

Create a process

POST /processes

process.manage

Process with its current and draft versions

GET /processes/{key}

process.read

New draft

POST /processes/{key}/versions

process.manage

Read a version

GET /process-versions/{id}

process.read

Replace a draft's steps

PATCH /process-versions/{id}

process.manage

Publish a draft

POST /process-versions/{id}/publish

process.manage

Start

POST /processes/{key}/start

process.execute

List instances

GET /process-instances

process.read

Full instance

GET /process-instances/{id}

process.read

Cancel an instance

POST /process-instances/{id}/cancel

process.execute

My approvals

GET /approvals

assignee

My approvals across all workspaces

GET /me/approvals

person's session only, assignee

Approval

GET /approvals/{id}

assignee or process.read

Decision

POST /approvals/{id}/decision

assignee

Ingest an external event

POST /events

integration.ingest_events or integration.manage

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

key

string

yes

Process key: ^[a-z][a-z0-9_]{0,62}$, immutable

name

string

yes

Name, 1–200 characters

object_type

string or null

no

Key or id of the object type. Without it the process runs without an object

execution_principal_id

uuid

yes

On whose behalf the steps run. This is you or an active service principal; only a holder of workspace.manage can assign someone else's principal

start

string

yes

Key of the first step

steps

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.json

The 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.

type

Parameters

What it does

action

action, next, on_error?

Performs an automation action on the instance's object (same shape as in automations, except start_process). Without on_error, an action error fails the instance

wait

duration, next

Pause: an ISO 8601 duration, for example P3D or PT15M

wait_until

until, next

Waits until the moment given by an expression (date or time). A moment in the past moves on immediately

wait_event

event_type, correlation, timeout?, on_event, on_timeout

Waits for an external event of this type with the correlation key from the correlation expression

approval

assignees, policy, timeout?, on_approved, on_rejected, on_timeout, title?

Creates an approval and waits for a decision

branch

branches: [{when, next}], default?

Takes the first branch whose when condition is true; otherwise goes to default. 1–20 branches

parallel

branches: [step, …]

Starts 2–20 branches at once

join

mode: all | quorum, quorum?, next

Waits for all branches (or quorum) and moves on; the remaining branches are cancelled

escalate

notify, title?, body?, next

Sends a notification to Sensever chat

complete

—

Finishes the instance with status completed

fail

code, message?

Fails the instance: code in the form ^[A-Z][A-Z0-9_]*$

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

"0190…"

Principal by id

{"role": "owner"}

Everyone with the system role: owner, admin, member or viewer

{"role_id": "<uuid>"}

Everyone with a custom workspace role

{"field": "<field key>"}

People from an object field of type principal or multi_principal

{"object": "owner"}

The object's assignee; {"object": "creator"} — its author

{"expr": "<expression>"}

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}/versions with a {start, steps} body creates the next draft. A process has only one draft: a second one returns 422 VALIDATION_FAILED with details.reason = draft_exists.

  • PATCH /process-versions/{id} with the same body replaces the draft's steps entirely. A published or retired version returns 409 DEFINITION_IMMUTABLE.

  • POST /process-versions/{id}/publish with 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

object_id

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

input

object

no

Instance input, available in expressions as context.input. Up to 16 KB

start_key

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

error.code

When

404

PROCESS_NOT_FOUND

The process doesn't exist, is archived, or you can't see it. With details.reason = not_published, the process has no published version

404

OBJECT_NOT_FOUND

The object doesn't exist or you can't read it

409

OBJECT_ARCHIVED

The object is archived

422

VALIDATION_FAILED

No object_id for a process with a type, an object of another type, an object_id for a process without a type, an invalid start_key

403

PERMISSION_DENIED

No process.execute permission

Instance

Field

Description

id

Instance id

process

{id, key} of the process

version_id, process_version

The version the instance runs on

object_id

The object or null

status

running, completed, failed, cancelled

input

Start input

steps

Results of completed steps: {"<step>": {"outcome": "…", "result": {…}}}

version

The instance's version number, grows with each step

start_key

Start key or null

correlation_id

End-to-end id of the event chain

started_by

{type, id} — who started it

error

Failure error (code, message, step_key…) or {code: PROCESS_CANCELLED, cause: api | object_archived} for a cancelled one

started_at, updated_at, completed_at

Timestamps

tokens

Execution positions in the graph: step_key, status (ready, waiting, completed, cancelled, failed), parent_token_id, attempt

waits

Event waits: event_type, correlation_key, status (pending, resolved, expired, cancelled), resolved_event_id

approvals

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

object_id

Only instances of this object

process

Only this process (key or id). An unknown or invisible process yields an empty page

status

running, completed, failed or cancelled

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

assigned_to

Only me (default)

status

pending (default) — awaiting your decision; all — decided and closed ones too

Approval (Approval):

Field

Description

id, instance_id, token_id

Ids of the approval, the instance and the step token

step_key, process_key

Step and process

title

Title from the step

object_id

The instance's object or null

policy

{mode: any | all | quorum, quorum?}

status

pending, approved, rejected, expired, cancelled

created_at, decided_at

Timestamps

assignments

Assignees: principal_id, decision (approved, rejected or null), comment, decided_at

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

status

pending (default) or all

workspace_id

Only this workspace (id from GET /me)

page[size]

1–100, default 50

page[cursor]

next_cursor of the previous page with the same status and workspace_id

In each workspace the selection is the same as GET /approvals?assigned_to=me there. Order: newest first. A response item:

Field

Description

approval

The approval (Approval, see above)

workspace

Workspace: id, name, is_system

principal_id

The person's member in this workspace — its id appears in approval.assignments

can_decide

true if the approval awaits a decision and the person hasn't voted yet

assignee_names

Assignee names by principal_id; empty if there is no workspace.read permission in this workspace

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

decision

string

yes

approved or rejected

comment

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

error.code

When

422

APPROVAL_NOT_ASSIGNED

You aren't assigned to this approval

409

APPROVAL_ALREADY_DECIDED

You've already decided, or the approval is closed

404

NOT_FOUND

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

source

string

yes

Source key: ^[a-z][a-z0-9_.-]{0,62}$, for example erp

external_event_id

string

yes

Event id in the source, 1–255 characters. Together with source, it is the event's identity

event_type

string

yes

Type: lowercase segments separated by dots, for example erp.payment_received, up to 128 characters

correlation_key

string

yes

Correlation key, 1–512 characters. Matches correlation of wait_event steps; for automations, the object id

payload

object

yes

Event body, up to 256 KB. Stored for 90 days

occurred_at

string or null

no

Event time in the source (RFC 3339)

schema_version

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_event waits with the same event_type and correlation_key are resolved, and external.event_received is published.

  • Retry with the same content — 200, duplicate: true, the original event_id. Nothing advances a second time; resolved_waits is 0.

  • Same id with different content — 422 EXTERNAL_EVENT_CONFLICT: event_type, correlation_key or payload differs (compared by value). details contains source, external_event_id and the event_id of 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

error.code

When

413

PAYLOAD_TOO_LARGE

payload is larger than 256 KB

422

VALIDATION_FAILED

Invalid field format or missing Idempotency-Key

403

PERMISSION_DENIED

No integration.ingest_events permission (it is granted by integration.manage and the system roles owner, admin and integration)

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

process.published

A process version was published

process.started

An instance was started

process.step_completed

A step was completed: step_key, token_id, outcome

process.completed, process.failed, process.cancelled

An instance finished

approval.requested, approval.decided

An approval was created, a decision was made

external.event_received

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.

Komentarze

Autorzy