ConnectCloud Developers

Change notices for open forge pages (tenant:forge:read)

GET /api/forge/v1/live

Module: Forge · operationId: streamForgeLiveChanges · Tag: Status · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read. Answers text/event-stream (X-Accel-Buffering: no, a : ping comment every 15 seconds). First a ready event ({}), then one change event per item, project or configuration change of a project the caller sees (the rule of GET /projects/{key}: visibility and membership), 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 – never title or content; the client reloads it through the API. kind is item (action = the history action, projectId, projectKey, itemId, number, ref), project (action saved with projectId and projectKey – also members and repositories –, or deleted with projectId only, sent to whoever could see the project before), config (projectId: reload the project's configuration; no actor) 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. Any other end means notices may be missing; the client reloads what it shows. At most 10 open streams per person and 500 per tenant and server instance (429 rate_limited).

Responses

  • 200 Event stream (text/event-stream)
  • 401 Error (application/json)
  • 403 Error (application/json)
  • 429 Error (application/json)
  • 503 Error (application/json)

Fields of the 200 answer:

  • kind (string, required): What changed (resync: notices were dropped, reload everything) (one of item, project, config, milestone, iteration, resync)
  • action (string): item: the history action (created, updated, status_changed, commented, …); project: saved or deleted; milestone: saved, closed, reopened or deleted; iteration: saved, started, closed or deleted
  • itemId (string (uuid)): Item of an item notice
  • iterationId (string (uuid)): Iteration of an iteration notice
  • milestoneId (string (uuid)): Milestone of a milestone notice
  • number (integer): Number of the item
  • projectId (string (uuid)): Project of the change
  • projectKey (string): Key of the project
  • ref (string): Item reference, e.g. APP-12

Example request

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

View as Markdown · Interactive reference · OpenAPI