Change notices for open flows pages (tenant:flows:read|write|admin|tasks)
GET /api/flows/v1/live
Module: Flows · operationId: streamFlowsLiveChanges · Tag: Runs · Auth: access token (Authorization: Bearer <accessToken>)
Answers text/event-stream (X-Accel-Buffering: no, a : ping comment every 15 seconds). First a ready event
({}), then one change event per flow, run or task change the caller may see – with the rules of the read
routes: a flow as GET /flows/{id}, a run as GET /runs/{id}, a task as GET /tasks/{id} (its assignees with
tenant:flows:tasks, and who sees its run) – about one to two seconds after the commit; a new stream starts with
the changes of the last 10 seconds. A notice only names what changed (ids, action, state) – never names, data or
definitions; the client reloads through the API. kind is flow (action created, updated, published,
archived, tripped), run (action started, succeeded, failed, cancelled; status of an ended run), task
(action created, completed; status) or resync (notices were dropped: reload everything shown). When the
token expires, and after 15 minutes at the latest, the stream ends with a reconnect event ({}): reconnecting
within 10 seconds loses nothing. At most 10 open streams per person and 500 per tenant and server instance
(429 rate_limited).
The notices of a scoped flow (its flow, run and task changes) reach only a stream that names its scope with
scope – besides a task's assignees, who always hear of their task. Each named scope is checked once, when
the stream opens: the module that owns it must let the caller view it (404 otherwise, 503 scope_unavailable when it cannot answer); the check is repeated at every reconnect, so a changed answer
applies after 15 minutes at the latest. A stream that names scopes still carries the caller's other notices.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
scope |
query | array of string | Also stream the changes of this scope's flows (desk:space:<id>, forge:project:<id>); repeatable, at most 10 (400 invalid, field scope) |
Responses
- 200 Event stream (
text/event-stream) - 400 Invalid input (
invalid);fieldnames the first invalid field,details.fieldsevery one. (application/json) - 401 Missing, invalid or expired token (no body).
- 403 The token lacks the permission or has no active tenant (
forbidden). Also:person_required(a service-account key on personal flows or the task inbox),live_test_forbidden,forbidden_grant,starter_excluded. (application/json) - 404 The record does not exist in the token's tenant – or it belongs to a scope the caller may not view (a scoped flow stays hidden). (
application/json) - 429 Too many open streams (
rate_limited) - 503 A dependency is not available:
scope_unavailable(the module that owns a flow's scope did not answer who may see and manage it – nothing of a scoped flow is shown or changed),identity_unavailable(HR),ai_unavailable,ai_failed. (application/json)
Fields of the 200 answer:
kind(string, required): What changed (one offlow,run,task,resync)action(string): What happened to itflowId(string (uuid)): The flowrunId(string (uuid)): The runstatus(string): State of an ended run or of a tasktaskId(string (uuid)): The task
Example request
curl -X GET 'https://api.mbcom.cloud/api/flows/v1/live' \
-H "Authorization: Bearer $ACCESS_TOKEN"