canonical: https://jentic.com/apis/liveblocks.io/liveblocks # Liveblocks REST API Liveblocks is a real-time collaboration platform. Its REST API manages collaboration rooms, room storage, Yjs documents (binary and structured), threaded comments with reactions, and version snapshots for time-travel and audit. Built around the Room as the central resource, the API lets backend services provision rooms, broadcast events to connected clients, manage thread and comment lifecycles, and pull or initialise per-room storage. Authentication uses a Bearer token issued from the Liveblocks dashboard. ## For AI agents Provision Liveblocks collaboration rooms, manage Yjs documents and storage, drive threaded comments and versions, and broadcast events to connected clients from a backend. ## Scope Does not handle video conferencing, voice, or end-user authentication UI - use for backend collaboration room, Yjs document, comment, and version management only. ## Capabilities - Provision and configure collaboration rooms via POST /rooms, GET /rooms, and POST `/rooms/{roomId}` - Read and reset per-room storage via GET, POST, and DELETE `/rooms/{roomId}/storage` - Operate Yjs documents in JSON or binary form via `/rooms/{roomId}/ydoc` and `/rooms/{roomId}/ydoc-binary` - Manage threaded comments and reactions via `/rooms/{roomId}/threads/{threadId}/comments` endpoints - Snapshot and restore room versions via `/rooms/{roomId}/version` and `/rooms/{roomId}/versions` - Broadcast custom events to all connected room clients via POST `/rooms/{roomId}/broadcast_event` - Authenticate every request with a Bearer token issued from the Liveblocks dashboard ## Use cases ### Server-Side Room Provisioning Provision Liveblocks rooms from a backend when documents are created so collaboration is ready before any client connects. POST /rooms creates a room with a roomId and access permissions, GET /rooms lists existing rooms for management UIs, and DELETE `/rooms/{roomId}` cleans up when documents are deleted. Useful for SaaS apps that mirror room lifecycle to their own document objects. Example prompt: POST /rooms with roomId={doc-id} and permissions, then DELETE `/rooms/{roomId}` when the document is removed. ### Yjs Document Persistence Persist or restore Yjs collaboration state outside of Liveblocks for backup, exports, or cross-environment promotion. GET `/rooms/{roomId}/ydoc-binary` returns the binary Yjs document, PUT `/rooms/{roomId}/ydoc` updates it, and the JSON variant via GET `/rooms/{roomId}/ydoc` supports inspection for debugging. Best when teams need to back up collaborative documents nightly or migrate state between staging and production. Example prompt: Call GET `/rooms/{roomId}/ydoc-binary` nightly and store the bytes in object storage as a backup of the room's collaborative state. ### Threaded Comments and Reactions Power threaded comments, replies, and emoji reactions on top of Liveblocks rooms with a fully server-managed comment store. POST `/rooms/{roomId}/threads` creates a thread, POST `/rooms/{roomId}/threads/{threadId}/comments` adds replies, and POST `/rooms/{roomId}/threads/{threadId}/comments/{commentId}/add-reaction` handles reactions. Suitable for design tools, docs, and review experiences. Example prompt: POST `/rooms/{roomId}/threads` to create a comment thread on a selection, then POST a child comment to `/rooms/{roomId}/threads/{threadId}/comments.` ### Version Snapshots and Restore Snapshot and restore room state to support undo, version history, and audit trails. POST `/rooms/{roomId}/version` creates a named version, GET `/rooms/{roomId}/versions` lists snapshots, and GET `/rooms/{roomId}/version/{versionId}` returns a specific snapshot. Useful for design tools and document apps that need point-in-time recovery without rebuilding their own version model. Example prompt: POST `/rooms/{roomId}/version` every 10 minutes and GET `/rooms/{roomId}/versions` to render a version timeline in the UI. ### AI Agent Collaboration Hooks Let an AI agent join a Liveblocks-backed document, broadcast events, drop comments, or version-tag the room without holding the Bearer secret. Through Jentic, the agent searches by intent and gets the right /rooms or /threads endpoint with its schema while credentials stay in your Jentic One instance. The agent can then react to user activity or post structured comments back into the document thread. Example prompt: Search Jentic for 'broadcast a Liveblocks room event', load the schema, and execute POST `/rooms/{roomId}/broadcast_event` when the agent has a comment to deliver. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/rooms` | Create a collaboration room | | GET | `/rooms` | List rooms | | POST | `/rooms/{roomId}/broadcast_event` | Broadcast event to room clients | | GET | `/rooms/{roomId}/ydoc-binary` | Get Yjs document as binary | | POST | `/rooms/{roomId}/threads` | Create a comment thread | | POST | `/rooms/{roomId}/threads/{threadId}/comments` | Create a comment on a thread | | POST | `/rooms/{roomId}/version` | Create a version snapshot | ## Key resources - **Rooms** — Provision, list, update, and delete collaboration rooms via /rooms and `/rooms/{roomId}` - **Storage** — Per-room storage initialise, read, and clear via `/rooms/{roomId}/storage` - **Yjs Documents** — Yjs JSON and binary document access via `/rooms/{roomId}/ydoc` and `/rooms/{roomId}/ydoc-binary` - **Threads** — Comment thread lifecycle via `/rooms/{roomId}/threads` and `/rooms/{roomId}/threads/{threadId}` - **Comments** — Comment creation, update, delete, and reactions via `/rooms/{roomId}/threads/{threadId}/comments` endpoints - **Versions** — Version snapshots via `/rooms/{roomId}/version` and `/rooms/{roomId}/versions` ## Why Jentic - **Setup:** Wiring the Liveblocks REST API by hand means setting up its bearer secret auth, attaching the Authorization header to every call against api.liveblocks.io, and handling retries yourself across room and thread operations. Through Jentic you install once, import the Liveblocks REST API from the API Directory, store the secret once, and your agent calls it. - **Permission scoping:** Liveblocks puts the room id in the URL path (`/rooms/{roomId}/...`), so a rule can pin your agent to one room: it can broadcast events, post threads, and add comments there and nothing else. You choose the operations it may call, so room creation with POST /rooms is not included unless you add it. - **Credential handling:** Your Liveblocks secret is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a Liveblocks room' or 'broadcast a room event', and Jentic returns the matching Liveblocks operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Pusher API** — Hosted real-time messaging for channels and presence without document storage - **Firebase API** — Realtime Database and Firestore for backend-synced collaboration state - **OpenAI API** — LLM provider for agents that comment or summarise inside Liveblocks documents ## FAQ ### What authentication does the Liveblocks REST API use? The Liveblocks REST API uses Bearer token auth (the BearerAuth scheme in the spec). Tokens are issued from the Liveblocks dashboard. Through Jentic, the secret is held in your Jentic One instance and injected as the Authorization header at execution time. ### Can I create and broadcast to rooms with the Liveblocks API? Yes. POST /rooms creates a room with a roomId and permissions, and POST `/rooms/{roomId}/broadcast_event` sends a custom event to all connected clients. GET `/rooms/{roomId}/active_users` returns the currently connected users for monitoring or presence-driven workflows. ### What are the rate limits for the Liveblocks REST API? Rate limits are enforced per project and tier, with stricter limits on write-heavy endpoints like `/rooms/{roomId}/broadcast_event.` Build agents to back off on 429 responses and to batch comment operations rather than calling `/threads/{threadId}/comments` in tight loops. ### How do I create a Liveblocks room through Jentic? Run pip install jentic, then search for 'create a Liveblocks collaboration room'. Jentic returns POST /rooms. Load the schema, supply roomId and permissions, and execute. Use DELETE `/rooms/{roomId}` when the document is removed to keep the room list clean. ### Does the Liveblocks API expose Yjs documents directly? Yes. GET `/rooms/{roomId}/ydoc` returns the document as JSON for inspection, GET `/rooms/{roomId}/ydoc-binary` returns it in Yjs binary form for backup or migration, and PUT `/rooms/{roomId}/ydoc` updates the document state. Use the binary form for round-trip persistence. ### Can I limit what my agent is allowed to do with the Liveblocks REST API? Yes. Because you run Jentic One yourself, your own rules decide which Liveblocks operations and credentials the agent can use. Since the room id sits in the URL path (`/rooms/{roomId}/...`), a rule can pin the agent to a single room so it can broadcast events with POST `/rooms/{roomId}/broadcast_event`, open threads with POST `/rooms/{roomId}/threads`, and add comments there and nowhere else. You pick the exact operations it may call, so room creation with POST /rooms stays off the list unless you explicitly allow it.