Skip to main content

Collaboration — Presence & Comments

Tags: Presence, Comments · Version: v1 · Stability: 🟡 Beta

Real-time-ish collaboration without full co-editing: see who's looking at a template, and discuss it inline with @mentions. Both are JWT-only and workspace-scoped.

:::info Versioning These endpoints are 🟡 Beta — functionally complete and shipped end-to-end, but newer than the core surface and may still gain response fields within v1. Pin to the documented fields. :::

Presence​

Presence is poll-based: clients send a heartbeat while viewing a resource and fetch the current viewers. (No WebSockets yet.)

Send a heartbeat​

POST /api/presence · JWT

Request — HeartbeatBody
{ "resourceType": "template", "resourceId": "3f6b…uuid" }

Both fields required (resourceId is a UUID). Call periodically while a user views the resource to keep them shown as present.

Get current viewers​

GET /api/presence/{resourceType}/{resourceId} · JWT — who is currently viewing this resource (e.g. "Sarah is viewing this template").

Clear presence​

DELETE /api/presence/{resourceType}/{resourceId} · JWT — explicitly mark the user as no longer viewing (e.g. on navigate-away).

{resourceType} is a string (e.g. template); {resourceId} is a UUID.

Comments​

Threaded discussion attached to a template, with @mention resolution.

List comments​

GET /api/templates/{templateId}/comments · JWT — {templateId} is a UUID.

Add a comment​

POST /api/templates/{templateId}/comments · JWT

Request — CreateCommentBody
{ "body": "Can we move the logo up? cc @sarah" }

body is required. @mentions are resolved to workspace members.

Delete a comment​

DELETE /api/templates/{templateId}/comments/{commentId} · JWT

{commentId} is a UUID. Allowed for the comment author or a workspace Owner — otherwise 403 Forbidden.