Liveblocks REST API allows developers to interact programmatically with their Liveblocks account and services using HTTP requests. With the API, developers can retrieve, set, and udpate room-related data, users, permissions, schemas, and more. The Liveblocks API is organized around REST.
The API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
To use the API endpoints, you need to add your secret key to the requestβs authorization header. Except for the public authorization endpoint.
This endpoint lets your application server (your back end) obtain a token that one of its clients (your frontend) can use to enter a Liveblocks room. You use this endpoint to implement your own applicationβs custom authentication endpoint. When making this request, youβll have to use your secret key.
Important: The difference with an ID token is that an access token holds all the permissions, and is the source of truth. With ID tokens, permissions are set in the Liveblocks back end (through REST API calls) and "checked at the door" every time they are used to enter a room.
Note: When using the @liveblocks/node
package, you can use Liveblocks.prepareSession
in your back end to build this request.
You can pass the property userId
in the requestβs body. This can be whatever internal identifier you use for your user accounts as long as it uniquely identifies an account. The property userId
is used by Liveblocks to calculate your accountβs Monthly Active Users. One unique userId
corresponds to one MAU.
Additionally, you can set custom metadata to the token, which will be publicly accessible by other clients through the user.info
property. This is useful for storing static data like avatar images or the userβs display name.
Lastly, youβll specify the exact permissions to give to the user using the permissions
field. This is done in an object where the keys are room names, or room name patterns (ending in a *
), and a list of permissions to assign the user for any room that matches that name exactly (or starts with the patternβs prefix). For tips, see Manage permissions with access tokens.
Success. Returns an access token that can be used to enter one or more rooms.
This endpoint lets your application server (your back end) obtain a token that one of its clients (your frontend) can use to enter a Liveblocks room. You use this endpoint to implement your own applicationβs custom authentication endpoint. When using this endpoint to obtain ID tokens, you should manage your permissions by assigning user and/or group permissions to rooms explicitly, see our Manage permissions with ID tokens section.
Important: The difference with an access token is that an ID token doesnβt hold any permissions itself. With ID tokens, permissions are set in the Liveblocks back end (through REST API calls) and "checked at the door" every time they are used to enter a room. With access tokens, all permissions are set in the token itself, and thus controlled from your back end entirely.
Note: When using the @liveblocks/node
package, you can use Liveblocks.identifyUser
in your back end to build this request.
You can pass the property userId
in the requestβs body. This can be whatever internal identifier you use for your user accounts as long as it uniquely identifies an account. The property userId
is used by Liveblocks to calculate your accountβs Monthly Active Users. One unique userId
corresponds to one MAU.
If you want to use group permissions, you can also declare which groupIds
this user belongs to. The group ID values are yours, but they will have to match the group IDs you assign permissions to when assigning permissions to rooms, see Manage permissions with ID tokens).
Additionally, you can set custom metadata to the token, which will be publicly accessible by other clients through the user.info
property. This is useful for storing static data like avatar images or the userβs display name.
Success. Returns an ID token that can be used to enter one or more rooms.
This endpoint returns a list of your rooms. The rooms are returned sorted by creation date, from newest to oldest. You can filter rooms by room ID prefixes, metadata, users accesses, and groups accesses. Corresponds to liveblocks.getRooms
.
There is a pagination system where the next page URL is returned in the response as nextPage
. You can also paginate by using nextCursor
in combination with startingAfter
.
You can also limit the number of rooms by query.
Filtering by metadata works by giving key values like metadata.color=red
. Of course you can combine multiple metadata clauses to refine the response like metadata.color=red&metadata.type=text
. Notice here the operator AND is applied between each clauses.
Filtering by groups or userId works by giving a list of groups like groupIds=marketing,GZo7tQ,product
or/and a userId like userId=user1
.
Notice here the operator OR is applied between each groupIds
and the userId
.
limit
optionalA limit on the number of rooms to be returned. The limit can range between 1 and 100, and defaults to 20.
startingAfter
optionalA cursor used for pagination. Get the value from the nextCursor
response of the previous page.
query
optionalQuery to filter rooms. You can filter by roomId
and metadata
, for example, metadata["roomType"]:"whiteboard" AND roomId^"liveblocks:engineering"
. Learn more about filtering rooms with query language.
userId
optionalA filter on users accesses.
groupIds
optionalA filter on groups accesses. Multiple groups can be used.
Success. Returns the list of rooms, the next page cursor, and the next page URL.
This endpoint creates a new room. id
and defaultAccesses
are required. Corresponds to liveblocks.createRoom
.
defaultAccessess
could be []
or ["room:write"]
(private or public).metadata
could be key/value as string
or string[]
. metadata
supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 256 characters maximum. metadata
is optional field.usersAccesses
could be []
or ["room:write"]
for every records. usersAccesses
can contain 100 ids maximum. Id length has a limit of 40 characters. usersAccesses
is optional field.groupsAccesses
are optional fields.Success. Returns the created room.
This endpoint returns a room by its ID. Corresponds to liveblocks.getRoom
.
roomId
requiredID of the room
Success. Returns the room.
This endpoint updates specific properties of a room. Corresponds to liveblocks.updateRoom
.
Itβs not necessary to provide the entire roomβs information.
Setting a property to null
means to delete this property. For example, if you want to remove access to a specific user without losing other users:
{ "usersAccesses": { "john": null } }
defaultAccessess
, metadata
, usersAccesses
, groupsAccesses
can be updated.
defaultAccessess
could be []
or ["room:write"]
(private or public).metadata
could be key/value as string
or string[]
. metadata
supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 256 characters maximum. metadata
is optional field.usersAccesses
could be []
or ["room:write"]
for every records. usersAccesses
can contain 100 ids maximum. Id length has a limit of 256 characters. usersAccesses
is optional field.groupsAccesses
could be []
or ["room:write"]
for every records. groupsAccesses
can contain 100 ids maximum. Id length has a limit of 256 characters. groupsAccesses
is optional field.roomId
requiredID of the room
Success. Returns the updated room.
This endpoint deletes a room. A deleted room is no longer accessible from the API or the dashboard and it cannot be restored. Corresponds to liveblocks.deleteRoom
.
roomId
requiredID of the room
This endpoint permanently updates the roomβs ID.
roomId
requiredThe new ID for the room
Success. Returns the updated room with the new ID.
This endpoint returns a list of users currently present in the requested room. Corresponds to liveblocks.getActiveUsers
.
For optimal performance, we recommend calling this endpoint no more than once every 10 seconds. Duplicates can occur if a user is in the requested room with multiple browser tabs opened.
roomId
requiredID of the room
Success. Returns the list of active users for the specified room.
This endpoint enables the broadcast of an event to a room without having to connect to it via the client
from @liveblocks/client
. It takes any valid JSON as a request body. The connectionId
passed to event listeners is -1
when using this API. Corresponds to liveblocks.broadcastEvent
.
roomId
requiredID of the room
Returns the contents of the roomβs Storage tree. Corresponds to liveblocks.getStorageDocument
.
The default outputted format is called βplain LSONβ, which includes information on the Live data structures in the tree. These nodes show up in the output as objects with two properties, for example:
If youβre not interested in this information, you can use the simpler ?format=json
query param, see below.
roomId
requiredID of the room
format
optionalUse ?format=json
to output a simplified JSON representation of the Storage tree. In that format, each LiveObject and LiveMap will be formatted as a simple JSON object, and each LiveList will be formatted as a simple JSON array. This is a lossy format because information about the original data structures is not retained, but it may be easier to work with.
Success. Returns the roomβs Storage as JSON.
This endpoint initializes or reinitializes a roomβs Storage. The room must already exist. Calling this endpoint will disconnect all users from the room if there are any, triggering a reconnect. Corresponds to liveblocks.initializeStorageDocument
.
The format of the request body is the same as whatβs returned by the get Storage endpoint.
For each Liveblocks data structure that you want to create, you need a JSON element having two properties:
"liveblocksType"
=> "LiveObject" | "LiveList" | "LiveMap"
"data"
=> contains the nested data structures (children) and data.The rootβs type can only be LiveObject.
A utility function, toPlainLson
is included in @liveblocks/client
from 1.0.9
to help convert LiveObject
, LiveList
, and LiveMap
to the structure expected by the endpoint.
roomId
requiredID of the room
Success. The Storage is initialized. Returns the roomβs Storage as JSON.
This endpoint deletes all of the roomβs Storage data. Calling this endpoint will disconnect all users from the room if there are any. Corresponds to liveblocks.deleteStorageDocument
.
roomId
requiredID of the room
This endpoint returns a JSON representation of the roomβs Yjs document. Corresponds to liveblocks.getYjsDocument
.
roomId
requiredID of the room
formatting
optionalIf present, YText will return formatting.
key
optionalReturns only a single keyβs value, e.g. doc.get(key).toJSON()
.
type
optionalUsed with key to override the inferred type, i.e. "ymap"
will return doc.get(key, Y.Map)
.
Success. Returns the roomβs Yjs document as JSON.
This endpoint is used to send a Yjs binary update to the roomβs Yjs document. You can use this endpoint to initialize Yjs data for the room or to update the roomβs Yjs document. To send an update to a subdocument instead of the main document, pass its guid
. Corresponds to liveblocks.sendYjsBinaryUpdate
.
The update is typically obtained by calling Y.encodeStateAsUpdate(doc)
. See the Yjs documentation for more details. When manually making this HTTP call, set the HTTP header Content-Type
to application/octet-stream
, and send the binary update (a Uint8Array
) in the body of the HTTP request. This endpoint does not accept JSON, unlike most other endpoints.
roomId
requiredID of the room
guid
optionalID of the subdocument
Success. The given roomβs Yjs doc has been updated.
This endpoint returns the roomβs Yjs document encoded as a single binary update. This can be used by Y.applyUpdate(responseBody)
to get a copy of the document in your back end. See Yjs documentation for more information on working with updates. To return a subdocument instead of the main document, pass its guid
. Corresponds to liveblocks.getYjsDocumentAsBinaryUpdate
.
roomId
requiredID of the room
guid
optionalID of the subdocument
This endpoint creates a new schema which can be referenced later to enforce a roomβs Storage data structure. Corresponds to liveblocks.createSchema
.
The schema consists of a name (for referencing it), and a body, which specifies the exact allowed shape of data in the room. This body is a multi-line string written in the Liveblocks schema syntax.
Success. Creates the new schema and returns it as JSON.
This endpoint retrieves a schema by its ID. The ID is a combination of the schema name and version. For example, my-schema@1
. Corresponds to liveblocks.getSchema
.
id
requiredID of the schema
Success. Found the schema and returns it as JSON.
This endpoint updates the body for the schema. A schema can only be updated if it is not used by any room. Corresponds to liveblocks.updateSchema
.
id
requiredID of the schema
Success. Updates the new schema and increments the version. The schema body
is returned as JSON.
This endpoint deletes a schema by its ID. The ID is a combination of the schema name and version. For example, my-schema@1
. A schema can only be deleted if it is not attached to a room. Corresponds to liveblocks.deleteSchema
.
id
requiredID of the schema
This endpoint retrieves the schema attached to a room. Corresponds to liveblocks.getSchemaByRoomId
.
roomId
requiredID of the room
Success. Found the schema attached to the room and returns it as JSON.
This endpoint attaches a schema to a room, and instantly enables runtime schema validation for the room. Corresponds to liveblocks.attachSchemaToRoom
.
If the current contents of the roomβs Storage do not match the schema, attaching will fail and the error message will give details on why the schema failed to attach.
roomId
requiredID of the room
Success. Found the schema attached to the room. Returns the schema ID as JSON.
This endpoint detaches the schema from a room. Corresponds to liveblocks.detachSchemaFromRoom
.
roomId
requiredID of the room
This endpoint returns the threads in the requested room. Corresponds to liveblocks.getThreads
.
roomId
requiredID of the room
query
optionalQuery to filter threads. You can filter by metadata
and resolved
, for example, metadata["status"]:"open" AND metadata["color"]:"red" AND resolved:true
. Learn more about filtering threads with query language.
Success. Returns list of threads in a room.
This endpoint creates a new thread and the first comment in the thread. Corresponds to liveblocks.createThread
.
A commentβs body is an array of paragraphs, each containing child nodes. Hereβs an example of how to construct a commentβs body, which can be submitted under comment.body
.
roomId
requiredID of the room
Success. Returns the created thread.
This endpoint returns a thread by its ID. Corresponds to liveblocks.getThread
.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns requested thread.
This endpoint deletes a thread by its ID. Corresponds to liveblocks.deleteThread
.
roomId
requiredID of the room
threadId
requiredID of the thread
This endpoint returns the list of thread participants. It is a list of unique user IDs representing all the thread comment authors and mentioned users in comments. Corresponds to liveblocks.getThreadParticipants
.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns the threadβs participants
This endpoint edits the metadata of a thread. The metadata is a JSON object that can be used to store any information you want about the thread, in string
, number
, or boolean
form. Set a property to null
to remove it. Corresponds to liveblocks.editThreadMetadata
.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns the updated metadata.
This endpoint marks a thread as resolved.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns the updated thread.
This endpoint marks a thread as unresolved.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns the updated thread.
This endpoint creates a new comment, adding it as a reply to a thread. Corresponds to liveblocks.createComment
.
A commentβs body is an array of paragraphs, each containing child nodes. Hereβs an example of how to construct a commentβs body, which can be submitted under body
.
roomId
requiredID of the room
threadId
requiredID of the thread
Success. Returns the created comment.
This endpoint returns a comment by its ID. Corresponds to liveblocks.getComment
.
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Success. Returns the requested comment.
This endpoint edits the specified comment. Corresponds to liveblocks.editComment
.
A commentβs body is an array of paragraphs, each containing child nodes. Hereβs an example of how to construct a commentβs body, which can be submitted under body
.
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Success. Returns the edited comment.
This endpoint deletes a comment. A deleted comment is no longer accessible from the API or the dashboard and it cannot be restored. Corresponds to liveblocks.deleteComment
.
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
This endpoint adds a reaction to a comment. Corresponds to liveblocks.addCommentReaction
.
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Success. Returns the created reaction.
This endpoint removes a comment reaction. A deleted comment reaction is no longer accessible from the API or the dashboard and it cannot be restored. Corresponds to liveblocks.removeCommentReaction
.
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
This endpoint returns a userβs inbox notification by its ID. Corresponds to liveblocks.getInboxNotification
.
userId
requiredID of the user
inboxNotificationId
requiredID of the inbox notification