ConnectCloud Developers

Change notices for open desk pages (desk:read)

GET /api/desk/v1/live

Module: Desk · operationId: streamLiveChanges · Tag: Configuration · 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 item, project or configuration change the caller may see, 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 – the client reloads it through the API. kind is item (with action, itemId, number, spaceId – empty when the item moved to a space the caller cannot see –, projectId, fromProjectId when it left a project, actor; also for its SLA warnings), project (projectId, number, actor), callback (action, callbackId, number, actor; only for callers with desk:write), config (reload the bootstrap) 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.

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: item, project, configuration; resync: notices were lost, reload everything (one of item, project, config, resync)
  • action (string): Action of the item event: created, updated, transitioned, commented, …, sla.warning, sla.breached, …
  • actor (string): Login of who made the change (not on config notices)
  • fromProjectId (string): The project the item left
  • itemId (string): Changed item
  • number (integer (int64)): Number of the changed item or project
  • projectId (string): The item's project, or the changed project
  • spaceId (string): Space of the changed item

Example request

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

View as Markdown · Interactive reference · OpenAPI