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.

https://api.liveblocks.io/v2

Authentication

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

$curl https://api.liveblocks.io/v2/* \  -H "Authorization: Bearer YOUR_SECRET_KEY"

Get rooms

GET
https://api.liveblocks.io/v2/rooms

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

limit optional

A limit on the number of rooms to be returned. The limit can range between 1 and 100, and defaults to 20.

  • Minimum: 1
  • Maximum: 100
  • Default: 20
startingAfter optional

A cursor used for pagination. You get the value from the response of the previous page.

metadata.KEY optional

A filter on metadata. Multiple metadata keys can be used to filter rooms.

metadata.colors=blue
userId optional

A filter on users accesses.

userId=user1
groupIds optional

A filter on groups accesses. Multiple groups can be used.

groupsIds=group1,group2
GET
https://api.liveblocks.io/v2/rooms

Responses

Status:

Success. Returns the list of rooms and the next page URL.

{  "nextPage": "/v2/rooms?startingAfter=W1siaWQiLCJVRzhWYl82SHRUS0NzXzFvci1HZHQiXSxbImNyZWF0ZWRBdCIsMTY2MDAwMDk4ODEzN11d",  "data": [    {      "type": "room",      "id": "HTOGSiXcORTECjfNBBLii",      "lastConnectionAt": "2022-08-08T23:23:15.281Z",      "createdAt": "2022-08-08T23:23:15.281Z",      "metadata": {        "name": [          "My room"        ],        "type": [          "whiteboard"        ]      },      "defaultAccesses": [        "room:write"      ],      "groupsAccesses": {        "product": [          "room:write"        ]      },      "usersAccesses": {        "vinod": [          "room:write"        ]      }    }  ]}

Create room

POST
https://api.liveblocks.io/v2/rooms

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"    ]  }}
POST
https://api.liveblocks.io/v2/rooms

Responses

Status:

Success. Returns the created room.

{  "type": "room",  "id": "my-room-3ebc26e2bf96",  "lastConnectionAt": "2022-08-22T15:10:25.225Z",  "createdAt": "2022-08-22T15:10:25.225Z",  "metadata": {    "color": "blue"  },  "defaultAccesses": [    "room:write"  ],  "groupsAccesses": {    "product": [      "room:write"    ]  },  "usersAccesses": {    "alice": [      "room:write"    ]  }}

Get room

GET
https://api.liveblocks.io/v2/rooms/{roomId}

Get a room by its ID.

Route parameters

roomId required

ID of the room

GET
https://api.liveblocks.io/v2/rooms/{roomId}

Responses

Status:

Success. Returns the room.

{  "type": "room",  "id": "react-todo-list",  "lastConnectionAt": "2022-08-04T21:07:09.380Z",  "createdAt": "2022-07-13T14:32:50.697Z",  "metadata": {    "color": "blue",    "size": "10",    "target": [      "abc",      "def"    ]  },  "defaultAccesses": [    "room:write"  ],  "groupsAccesses": {    "marketing": [      "room:write"    ]  },  "usersAccesses": {    "alice": [      "room:write"    ],    "vinod": [      "room:write"    ]  }}

Update room

POST
https://api.liveblocks.io/v2/rooms/{roomId}

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

roomId required

ID of the room

Request body

{  "defaultAccesses": [    "room:write"  ],  "usersAccesses": {    "vinod": [      "room:write"    ],    "alice": [      "room:write"    ]  },  "groupsAccesses": {    "marketing": [      "room:write"    ]  },  "metadata": {    "color": "blue"  }}
POST
https://api.liveblocks.io/v2/rooms/{roomId}

Responses

Status:

Success. Returns the updated room.

{  "type": "room",  "id": "react-todo-list",  "lastConnectionAt": "2022-08-04T21:07:09.380Z",  "createdAt": "2022-07-13T14:32:50.697Z",  "metadata": {    "color": "blue",    "size": "10",    "target": [      "abc",      "def"    ]  },  "defaultAccesses": [    "room:write"  ],  "groupsAccesses": {    "marketing": [      "room:write"    ]  },  "usersAccesses": {    "alice": [      "room:write"    ],    "vinod": [      "room:write"    ]  }}

Delete room

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}

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

Route parameters

roomId required

ID of the room

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}

Get active users

GET
https://api.liveblocks.io/v2/rooms/{roomId}/active_users

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

roomId required

ID of the room

GET
https://api.liveblocks.io/v2/rooms/{roomId}/active_users

Responses

Status:

Success. Returns the list of active users for the specified room.

{  "data": [    {      "type": "user",      "connectionId": 16,      "id": "alice",      "info": {}    },    {      "type": "user",      "connectionId": 20,      "id": "bob",      "info": {}    }  ]}

Get storage

GET
https://api.liveblocks.io/v2/rooms/{roomId}/storage

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

roomId required

ID of the room

GET
https://api.liveblocks.io/v2/rooms/{roomId}/storage

Responses

Status:

Success. Returns the room storage as JSON.

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

Initialize storage

POST
https://api.liveblocks.io/v2/rooms/{roomId}/storage

Initializes a room storage. The room must already exist and have an empty storage. Calling this endpoint will disconnect all users from the room if there are any.

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.

Route parameters

roomId required

ID of the room

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      }    }  }}
POST
https://api.liveblocks.io/v2/rooms/{roomId}/storage

Responses

Status:

Success. The storage is initialized. Returns the room storage as JSON.

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

Delete storage

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/storage

Deletes all of the room’s storage data. Calling this endpoint will disconnect all users from the room if there are any.

Route parameters

roomId required

ID of the room

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/storage

Get an access token to enter a room

POST
https://api.liveblocks.io/v2/rooms/{roomId}/authorize

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.

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. 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). In case you want to use the group permission system, you can also declare which groupIds this user belongs to.

The property userId is used by Liveblocks to calculate your account’s Monthly Active Users. One unique userId corresponds to one MAU. If you don’t pass a userId, we will create for you a new anonymous userId on each connection, but your MAUs will be higher.

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.

Route parameters

roomId required

ID of the room

Request body

{  "userId": "b2c1c290-f2c9-45de-a74e-6b7aa0690f59",  "groupIds": [    "g1",    "g2"  ],  "userInfo": {    "name": "bob",    "colors": [      "blue",      "red"    ]  }}
POST
https://api.liveblocks.io/v2/rooms/{roomId}/authorize

Responses

Status:

Success. Returns the JWT token.

{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}

Broadcast an event to a room

POST
https://api.liveblocks.io/v2/rooms/{roomId}/broadcast_event

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.

Parameters

roomId required

ID of the room

Request body

{  "type": "EMOJI",  "emoji": "🔥"}
POST
https://api.liveblocks.io/v2/rooms/{roomId}/broadcast_event

Get JWT token for WebSocket with public key

POST
https://api.liveblocks.io/v2/rooms/{roomId}/public/authorize

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

roomId required

ID of the room

Request body

{  "publicApiKey": "pk_test_lOMrmwejSWLaPYQc5_JuGHXXX"}
POST
https://api.liveblocks.io/v2/rooms/{roomId}/public/authorize

Responses

Status:

Success. Returns the JWT token.

{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}

Create schema

POST
https://api.liveblocks.io/v2/schemas

Creates a new schema which can be referenced later to enforce a room's storage data structure. 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.

Request body

{  "name": "my-schema",  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}
POST
https://api.liveblocks.io/v2/schemas

Responses

Status:

Success. Creates the new schema and returns it as JSON.

{  "id": "my-schema@1",  "name": "my-schema",  "version": 1,  "createdAt": "2023-03-30T06:25:54.675Z",  "updatedAt": "2023-03-30T06:25:54.675Z",  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}

Get schema

GET
https://api.liveblocks.io/v2/schemas/{id}

This endpoint retrieves a schema by its id. The id is a combination of the schema name and version. For example, my-schema@1.

Parameters

id required

ID of the schema

GET
https://api.liveblocks.io/v2/schemas/{id}

Responses

Status:

Success. Found the schema and returns it as JSON.

{  "id": "my-schema@1",  "name": "my-schema",  "version": 1,  "createdAt": "2023-03-30T06:25:54.675Z",  "updatedAt": "2023-03-30T06:25:54.675Z",  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}

Update schema

PUT
https://api.liveblocks.io/v2/schemas/{id}

Updates the body for the schema. A schema can only be updated if it is not used by any room.

Parameters

id required

ID of the schema

Request body

{  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}
PUT
https://api.liveblocks.io/v2/schemas/{id}

Responses

Status:

Success. Updates the new schema and increments the version. The schema body is returned as JSON.

{  "id": "my-schema@2",  "name": "my-schema",  "version": 2,  "createdAt": "2023-03-30T07:25:54.675Z",  "updatedAt": "2023-03-30T07:25:54.675Z",  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}

Delete schema

DELETE
https://api.liveblocks.io/v2/schemas/{id}

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.

Parameters

id required

ID of the schema

DELETE
https://api.liveblocks.io/v2/schemas/{id}

Get schema by room

GET
https://api.liveblocks.io/v2/rooms/{roomId}/schema

This endpoint retrieves the schema attached to a room.

Parameters

roomId required

ID of the room

GET
https://api.liveblocks.io/v2/rooms/{roomId}/schema

Responses

Status:

Success. Found the schema attached to the room and returns it as JSON.

{  "id": "my-schema@1",  "name": "my-schema",  "version": 1,  "createdAt": "2023-03-30T06:25:54.675Z",  "updatedAt": "2023-03-30T06:25:54.675Z",  "body": "type Logo {\nname: string\ntheme: string\n}\n\ntype Storage {\nlogo: LiveObject<Logo>\n"}

Attach schema to room

POST
https://api.liveblocks.io/v2/rooms/{roomId}/schema

This endpoint attachs a schema to a room, and instantly enables runtime schema validation for the room. 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.

Parameters

roomId required

ID of the room

Request body

{  "schema": "my-schema@1"}
POST
https://api.liveblocks.io/v2/rooms/{roomId}/schema

Responses

Status:

Success. Found the schema attached to the room. Returns the schema id as JSON.

{  "schema": "my-schema@1"}

Detach schema from room

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/schema

This endpoint detaches the schema from a room.

Parameters

roomId required

ID of the room

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/schema
Was this page helpful?
© 2023 Liveblocks Inc.