ConnectCloud Developers

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); field names the first invalid field, details.fields every 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 of flow, run, task, resync)
  • action (string): What happened to it
  • flowId (string (uuid)): The flow
  • runId (string (uuid)): The run
  • status (string): State of an ended run or of a task
  • taskId (string (uuid)): The task

Example request

curl -X GET 'https://api.mbcom.cloud/api/flows/v1/live' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI