Real-time Collaboration

Collaborate on documents in real time with conflict-free editing. Track version history, view diffs, revert changes, and sync offline edits.

WebSocket Connection

Real-time collaboration uses a two-step connect flow. First exchange your bearer token for a single-use connection ticket, then open the WebSocket with that ticket. Multiple users can edit the same document simultaneously, and conflicting edits are merged automatically.

Obtain a Connection Ticket

POST /v1/collaboration/ticket

Headers

Authorization: Bearer YOUR_ACCESS_TOKEN

Returns a short-lived, single-use ticket. Passing the ticket (rather than a JWT) in the WebSocket URL keeps the access token out of URLs, logs, and history.

Open the WebSocket

GET /v1/collaboration/ws?ticket=YOUR_TICKET

Connection Parameters

Parameter	Type	Description
`ticket`	string	Single-use ticket from `POST /v1/collaboration/ticket` (preferred)
`token`	string	Raw JWT access token (deprecated fallback; will be removed in a future release)

Each connection is scoped to your organization; the specific document is selected once the socket is open.

Security Notes

The ticket (or, on the deprecated path, the access token) is validated on WebSocket upgrade, including organization membership
Tickets are single-use and consumed on connect
WSS (TLS) transport is mandatory
Document access is verified against the user’s RBAC permissions
Awareness protocol broadcasts cursor positions and user presence

Version History

Version endpoints are addressed by resource type and resource ID. The supported resource types are skill, entity_type, screen_definition, workflow, pricing_plan, and tool.

Get Version History

GET /v1/versioning/:resourceType/:resourceId

Query Parameters

Parameter	Type	Description
`limit`	integer	Max results (default: 50, max: 100)
`offset`	integer	Pagination offset

Get a Specific Version

GET /v1/versioning/:resourceType/:resourceId/:version

Returns the stored snapshot for a single version number of the resource.

Revert to Version

POST /v1/versioning/:resourceType/:resourceId/revert

Request Body

{
  "version": 11,
  "changelog": "Reverting to the pre-migration requirements"
}

Revert the resource to a previous version number. This creates a new version with the reverted content rather than deleting intermediate versions. changelog is optional.

Offline Sync

Get Sync Preferences

GET /v1/sync/preferences

Response

{
  "data": {
    "user_id": "...",
    "org_id": "...",
    "enabled_sync_types": ["entities", "documents", "tasks"],
    "auto_sync": true,
    "sync_on_wifi_only": false,
    "max_local_size_mb": 500
  }
}

Update Sync Preferences

PUT /v1/sync/preferences

Selects which resource types are synced locally. Each requested type must be permitted by the organization’s sync configuration. Valid types are entities, relationships, documents, tasks, comments, and specs.

Request Body

{
  "enabled_sync_types": ["entities", "documents", "tasks"],
  "auto_sync": true,
  "sync_on_wifi_only": false
}

Pull Changes (Delta Sync)

GET /v1/sync/:resourceType

Pulls records for a synced resource type for the offline engine. Omit since for a full bulk download, or pass a millisecond epoch to fetch only records changed since then. Results use keyset pagination (nextCursor / hasMore) and incremental pulls may include "_deleted": true tombstones.

Query Parameters

Parameter	Type	Description
`since`	integer	Epoch milliseconds; returns only records changed since this time (optional)
`cursor`	string	Keyset pagination cursor from a previous response

Response

{
  "data": {
    "items": [],
    "hasMore": false,
    "nextCursor": null,
    "watermark": 1744483200000
  }
}