Liveblocks REST API

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.

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.

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 cursor to the next page is returned in the response as nextCursor, which can be combined 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.

This endpoint creates a new room. id and defaultAccesses are required. When provided with a ?idempotent query argument, will not return a 409 when the room already exists, but instead return the existing room as-is. Corresponds to liveblocks.createRoom, or to liveblocks.getOrCreateRoom when ?idempotent is provided.

• defaultAccesses is the default room permission list, for example [], ["*:read"], ["*:write"], or a more granular permission list.
• 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 contains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters. usersAccesses is optional field.
• groupsAccesses contains group-specific permission lists and is optional.

This endpoint returns a room by its ID. Corresponds to liveblocks.getRoom.

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 } } defaultAccesses, metadata, usersAccesses, groupsAccesses can be updated.

• defaultAccesses is the default room permission list, for example [], ["*:read"], ["*:write"], or a more granular permission list.
• 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 contains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters. usersAccesses is optional field.
• groupsAccesses contains group-specific permission lists and is optional.

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.

Speeds up connecting to a room for the next 10 seconds. Use this when you know a user will be connecting to a room with RoomProvider or enterRoom within 10 seconds, and the room will load quicker. Corresponds to liveblocks.prewarmRoom.

This endpoint updates specific properties of a room. Corresponds to liveblocks.upsertRoom.

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 } } defaultAccesses, metadata, usersAccesses, groupsAccesses can be updated.

• defaultAccesses is the default room permission list, for example [], ["*:read"], ["*:write"], or a more granular permission list.
• 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 contains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters. usersAccesses is optional field.
• groupsAccesses contains group-specific permission lists and is optional.

This endpoint permanently updates the room’s ID. All existing references to the old room ID will need to be updated. Returns the updated room. Corresponds to liveblocks.updateRoomId.

This endpoint updates the room's organization ID. The fromOrganizationId must match the room's current organization ID. Returns the updated room.

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.

This endpoint sets ephemeral presence for a user in a room without requiring a WebSocket connection. The presence data will automatically expire after the specified TTL (time-to-live). This is useful for scenarios like showing an AI agent's presence in a room. The presence will be broadcast to all connected users in the room. Corresponds to liveblocks.setPresence.

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.

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:

{  "liveblocksType": "LiveObject",  "data": ...}

If you’re not interested in this information, you can use the simpler ?format=json query param, see below.

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" | "LiveFile"
• "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, LiveMap, and LiveFile to the structure expected by the endpoint.

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.

Applies a sequence of JSON Patch operations to the room's Storage document, useful for modifying Storage. Operations are applied in order; if any operation fails, the document is not changed and a 422 response with a helpful message is returned.

Paths and data types: Be as specific as possible with your target path. Every parent in the chain of path segments must be a LiveObject, LiveList, or LiveMap. Complex nested objects passed in add or replace operations are automatically converted to LiveObjects and LiveLists. LiveText is a leaf node: only the LiveText node itself is addressable, not fields under its serialized data. Use replace with a string or a LiveTextData array to replace the whole node, for example /text with [["Hello"]]; use remove on /text to remove the node. LiveText versioning is internal and is not part of this API.

Performance: For large Storage documents, applying a patch can be expensive because the full state is reconstructed on the server to apply the operations. Very large documents may not be suitable for this endpoint.

For a full guide with examples, see Modifying storage via REST API with JSON Patch.

Returns an uploaded Storage file's metadata and a presigned download URL. The URL expires after one hour.

Uploads a file's bytes to a room and returns the metadata needed to create a LiveFile. For large files, use the multipart upload operations instead. Repeating the request with the same file ID, name, and file size returns the existing upload.

Starts a multipart upload for a Storage file.

Uploads one part of a Storage file multipart upload.

Completes a multipart upload and returns the metadata needed to create a LiveFile.