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 ofitem,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 deleteditemId(string (uuid)): Item of an item noticeiterationId(string (uuid)): Iteration of an iteration noticemilestoneId(string (uuid)): Milestone of a milestone noticenumber(integer): Number of the itemprojectId(string (uuid)): Project of the changeprojectKey(string): Key of the projectref(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"