API Reference - API Endpoints

The Liveblocks API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

With the Liveblocks API, you can authenticate requests, list and update rooms, list users, and more.

To use the API endpoints, you need to add your secret key to the request’s authorization header. Except for the public authorization endpoint.

Returns a list of your rooms. The rooms are returned sorted by creation date, from newest to oldest. You can filter rooms by metadata, users accesses and groups accesses.

There is a pagination system where the next page URL is returned in the response as nextPage. 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.

Parameters

metadata.colors=blue

userId=user1

groupsIds=group1,group2

Create a new room. id and defaultAccesses are required.

• 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.

Request body

{  "id": "my-room-3ebc26e2bf96",  "defaultAccesses": [    "room:write"  ],  "metadata": {    "color": "blue"  },  "usersAccesses": {    "alice": [      "room:write"    ]  },  "groupsAccesses": {    "product": [      "room:write"    ]  }}

Get a room by its id.

Route parameters

Updates specific properties of a room. 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.

Route parameters

Request body

{  "defaultAccesses": [    "room:write"  ],  "usersAccesses": {    "vinod": [      "room:write"    ],    "alice": [      "room:write"    ]  },  "groupsAccesses": {    "marketing": [      "room:write"    ]  },  "metadata": {    "color": "blue"  }}

Deletes a room. A deleted room is no longer accessible from the API or the dashboard and it cannot be restored.

Route parameters

Returns a list of users currently present in the requested room. For better performance, we recommand to call this endpoint every 10 seconds maximum. Duplicates can happen if a user is in the requested room with multiple browser tabs opened.

Route parameters

Returns a room storage as JSON.

Some implementation details: Each Liveblocks data structure is represented by a JSON element having two properties: "liveblocksType": "LiveObject" | "LiveList" | "LiveMap" "data" => contains the nested data structures (children) and data. The root is always a LiveObject.

Route parameters

Initializes a room storage. The room must already exist and have an empty storage.

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.

Route parameters

Request body

{  "liveblocksType": "LiveObject",  "data": {    "aLiveObject": {      "liveblocksType": "LiveObject",      "data": {        "a": 1      }    },    "aLiveList": {      "liveblocksType": "LiveList",      "data": [        "a",        "b"      ]    },    "aLiveMap": {      "liveblocksType": "LiveMap",      "data": {        "a": 1,        "b": 2      }    }  }}

Deletes all elements of the room storage.

Route parameters

This endpoint lets your application server (= your backend) 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.

The body for this POST request lets you declare what user ID the token is for, by means of the userId property. This can be whatever internal identifier you use for your user accounts, as long as it uniquely identifies an account. Setting the userId is optional if you want to use public rooms, but it is required to enter a private room (because permissions are assigned to specific user IDs). You can also declare which groupIds this user belongs to, in case you want to use the group permission system.

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 to store static data like avatar images, or the user's display name.

Route parameters

Request body

{  "userId": "b2c1c290-f2c9-45de-a74e-6b7aa0690f59",  "groupIds": [    "g1",    "g2"  ],  "userInfo": {    "name": "bob",    "colors": [      "blue",      "red"    ]  }}

This endpoint works with the public key and can be used client side. That means you don't need to implement a dedicated authorization endpoint server side. The generated JWT token works only with public room (defaultAccesses: ["room:write"]).

Route parameters

Request body

{  "publicApiKey": "pk_test_lOMrmwejSWLaPYQc5_JuGHXXX"}