API Reference - Liveblocks REST API

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.

https://api.liveblocks.io/v2

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"

Authentication

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.

Request body

POST
https://api.liveblocks.io/v2/authorize-user
{  "userId": "user-123",  "userInfo": {    "name": "bob",    "avatar": "https://example.org/images/user123.jpg"  },  "permissions": {    "my-room-1": [      "room:write"    ],    "my-room-2": [      "room:write"    ],    "my-room-*": [      "room:read"    ]  }}

Response

Status:

Success. Returns an access token that can be used to enter one or more rooms.

{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."}

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.

Request body

POST
https://api.liveblocks.io/v2/identify-user
{  "userId": "user-123",  "groupIds": [    "marketing",    "engineering"  ],  "userInfo": {    "name": "bob",    "avatar": "https://example.org/images/user123.jpg"  }}

Response

Status:

Success. Returns an ID token that can be used to enter one or more rooms.

{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIi..."}

Room

get/rooms

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

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. Get the value from the nextCursor response of the previous page.

  • metadata.KEY optional

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

  • userId optional

    A filter on users accesses.

  • groupIds optional

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

Request

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

Response

Status:

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

{  "nextCursor": "W1siaWQiLCJVRzhWYl82SHRUS0NzXzFvci1HZHQiXSxbImNyZWF0ZWRBdCIsMTY2MDAwMDk4ODEzN11d",  "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"        ]      }    }  ]}
post/rooms

Create room

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.

Request body

POST
https://api.liveblocks.io/v2/rooms
{  "id": "my-room-3ebc26e2bf96",  "defaultAccesses": [    "room:write"  ],  "metadata": {    "color": "blue"  },  "usersAccesses": {    "alice": [      "room:write"    ]  },  "groupsAccesses": {    "product": [      "room:write"    ]  }}

Response

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/rooms/:roomId

Get room

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

Parameters

  • roomId required

    ID of the room

Request

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

Response

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"    ]  }}
post/rooms/:roomId

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

Parameters

  • roomId required

    ID of the room

Request body

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

Response

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/rooms/:roomId

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

Parameters

  • roomId required

    ID of the room

Request

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}
post/rooms/:roomId/update-room-id

Update room ID

This endpoint permanently updates the room’s ID.

Parameters

  • newRoomId required

    The new ID for the room

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/update-room-id
{  "newRoomId": "new-room-id"}

Response

Status:

Success. Returns the updated room with the new ID.

{  "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"    ]  }}
get/rooms/:roomId/active_users

Get active users

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.

Parameters

  • roomId required

    ID of the room

Request

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

Response

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": {}    }  ]}
post/rooms/:roomId/broadcast_event

Broadcast event to a 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.

Parameters

  • roomId required

    ID of the room

Request body

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

Storage

get/rooms/:roomId/storage

Get Storage document

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.

Parameters

  • roomId required

    ID of the room

  • format optional

    Use ?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.

Request

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

Response

Status:

Success. Returns the room’s 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      }    }  }}
post/rooms/:roomId/storage

Initialize Storage document

This endpoint initializes a room’s 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. 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.

Parameters

  • roomId required

    ID of the room

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/storage
{  "liveblocksType": "LiveObject",  "data": {    "aLiveObject": {      "liveblocksType": "LiveObject",      "data": {        "a": 1      }    },    "aLiveList": {      "liveblocksType": "LiveList",      "data": [        "a",        "b"      ]    },    "aLiveMap": {      "liveblocksType": "LiveMap",      "data": {        "a": 1,        "b": 2      }    }  }}

Response

Status:

Success. The Storage is initialized. Returns the room’s 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/rooms/:roomId/storage

Delete Storage document

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.

Parameters

  • roomId required

    ID of the room

Request

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

Yjs

get/rooms/:roomId/ydoc

Get Yjs document

This endpoint returns a JSON representation of the room’s Yjs document. Corresponds to liveblocks.getYjsDocument.

Parameters

  • roomId required

    ID of the room

  • formatting optional

    If present, YText will return formatting.

  • key optional

    Returns only a single key’s value, e.g. doc.get(key).toJSON().

  • type optional

    Used with key to override the inferred type, i.e. "ymap" will return doc.get(key, Y.Map).

Request

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

Response

Status:

Success. Returns the room’s Yjs document as JSON.

{  "someYText": "Contents of YText"}
put/rooms/:roomId/ydoc

Send a binary Yjs update

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.

Parameters

  • roomId required

    ID of the room

  • guid optional

    ID of the subdocument

Request body

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

Response

Status:

Success. The given room’s Yjs doc has been updated.

{  "status": 200}

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.

Parameters

  • roomId required

    ID of the room

  • guid optional

    ID of the subdocument

Request

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

Schema validation

post/schemas

Create schema

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.

Request body

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

Response

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/schemas/:id

Get schema

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.

Parameters

  • id required

    ID of the schema

Request

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

Response

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"}
put/schemas/:id

Update schema

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.

Parameters

  • id required

    ID of the schema

Request body

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

Response

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/schemas/:id

Delete schema

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.

Parameters

  • id required

    ID of the schema

Request

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

Get schema by room ID

This endpoint retrieves the schema attached to a room. Corresponds to liveblocks.getSchemaByRoomId.

Parameters

  • roomId required

    ID of the room

Request

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

Response

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"}
post/rooms/:roomId/schema

Attach schema to room

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.

Parameters

  • roomId required

    ID of the room

Request body

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

Response

Status:

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

{  "schema": "my-schema@1"}
delete/rooms/:roomId/schema

Detach schema from room

This endpoint detaches the schema from a room. Corresponds to liveblocks.detachSchemaFromRoom.

Parameters

  • roomId required

    ID of the room

Request

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

Comments

get/rooms/:roomId/threads

Get room threads

This endpoint returns the threads in the requested room. Corresponds to liveblocks.getThreads.

Parameters

  • roomId required

    ID of the room

Request

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

Response

Status:

Success. Returns list of threads in a room.

{  "data": [    {      "type": "thread",      "id": "thread-id",      "roomId": "room-id",      "comments": [        {          "type": "comment",          "threadId": "thread-id",          "roomId": "room-id",          "id": "comment-id",          "userId": "string",          "createdAt": "2019-08-24T14:15:22Z",          "editedAt": "2019-08-24T14:15:22Z",          "deletedAt": "2019-08-24T14:15:22Z",          "body": {}        }      ],      "createdAt": "2019-08-24T14:15:22Z",      "metadata": {},      "updatedAt": "2019-08-24T14:15:22Z"    }  ]}
post/rooms/:roomId/threads

Create threadBeta

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.

"version": 1,"content": [  {    "type": "paragraph",    "children": [{ "text": "Hello " }, { "text": "world", "bold": true }]  }]

Parameters

  • roomId required

    ID of the room

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads
{  "comment": {    "userId": "alice",    "createdAt": "2022-07-13T14:32:50.697Z",    "body": {      "version": 1,      "content": []    }  },  "metadata": {    "color": "blue"  }}

Response

Status:

Success. Returns the created thread.

{  "type": "thread",  "id": "thread-id",  "roomId": "room-id",  "comments": [    {      "type": "comment",      "threadId": "thread-id",      "roomId": "room-id",      "id": "comment-id",      "userId": "alice",      "createdAt": "2022-07-13T14:32:50.697Z",      "body": {        "version": 1,        "content": []      }    }  ],  "createdAt": "2022-07-13T14:32:50.697Z",  "metadata": {    "color": "blue"  }}
get/rooms/:roomId/threads/:threadId

Get thread

This endpoint returns a thread by its ID. Corresponds to liveblocks.getThread.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

Request

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

Response

Status:

Success. Returns requested thread.

{  "type": "thread",  "id": "thread-id",  "roomId": "room-id",  "comments": [    {      "type": "comment",      "threadId": "thread-id",      "roomId": "room-id",      "id": "comment-id",      "userId": "string",      "createdAt": "2019-08-24T14:15:22Z",      "editedAt": "2019-08-24T14:15:22Z",      "deletedAt": "2019-08-24T14:15:22Z",      "body": {}    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "metadata": {},  "updatedAt": "2019-08-24T14:15:22Z"}
get/rooms/:roomId/threads/:threadId/participants

Get thread participants

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.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

Request

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

Response

Status:

Success. Returns the thread’s participants

{  "participantIds": [    "user-1",    "user-2"  ]}
post/rooms/:roomId/threads/:threadId/metadata

Edit thread metadataBeta

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.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/metadata
{  "metadata": {    "color": "yellow"  },  "userId": "alice",  "createdAt": "2023-07-13T14:32:50.697Z"}

Response

Status:

Success. Returns the updated metadata.

{  "color": "yellow"}
post/rooms/:roomId/threads/:threadId/comments

Create commentBeta

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.

"version": 1,"content": [  {    "type": "paragraph",    "children": [{ "text": "Hello " }, { "text": "world", "bold": true }]  }]

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments
{  "userId": "alice",  "createdAt": "2022-07-13T14:32:50.697Z",  "body": {    "version": 1,    "content": []  }}

Response

Status:

Success. Returns the created comment.

{  "type": "comment",  "threadId": "thread-id",  "roomId": "room-id",  "id": "comment-id",  "userId": "alice",  "createdAt": "2022-07-13T14:32:50.697Z",  "body": {    "version": 1,    "content": []  }}
get/rooms/:roomId/threads/:threadId/comments/:commentId

Get comment

This endpoint returns a comment by its ID. Corresponds to liveblocks.getComment.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

  • commentId required

    ID of the comment

Request

GET
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments/{commentId}

Response

Status:

Success. Returns the requested comment.

{  "type": "comment",  "threadId": "thread-id",  "roomId": "room-id",  "id": "comment-id",  "userId": "alice",  "createdAt": "2019-08-24T14:15:22Z",  "editedAt": "2019-08-24T14:15:22Z",  "deletedAt": "2019-08-24T14:15:22Z",  "body": {}}
post/rooms/:roomId/threads/:threadId/comments/:commentId

Edit commentBeta

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.

"version": 1,"content": [  {    "type": "paragraph",    "children": [{ "text": "Hello " }, { "text": "world", "bold": true }]  }]

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

  • commentId required

    ID of the comment

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments/{commentId}
{  "editedAt": "2023-07-13T14:32:50.697Z",  "body": {    "version": 1,    "content": []  }}

Response

Status:

Success. Returns the edited comment.

{  "type": "comment",  "threadId": "thread-id",  "roomId": "room-id",  "id": "comment-id",  "userId": "alice",  "createdAt": "2023-07-13T14:32:50.697Z",  "body": {    "version": 1,    "content": []  }}
delete/rooms/:roomId/threads/:threadId/comments/:commentId

Delete commentBeta

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.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

  • commentId required

    ID of the comment

Request

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments/{commentId}
post/rooms/:roomId/threads/:threadId/comments/:commentId/add-reaction

Add comment reactionBeta

This endpoint adds a reaction to a comment. Corresponds to liveblocks.addCommentReaction.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

  • commentId required

    ID of the comment

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments/{commentId}/add-reaction
{  "emoji": "👨‍👩‍👧",  "createdAt": "2022-07-13T14:32:50.697Z",  "userId": "alice"}

Response

Status:

Success. Returns the created reaction.

{  "emoji": "👨‍👩‍👧",  "createdAt": "2022-07-13T14:32:50.697Z",  "userId": "alice"}
post/rooms/:roomId/threads/:threadId/comments/:commentId/remove-reaction

Remove comment reactionBeta

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.

Parameters

  • roomId required

    ID of the room

  • threadId required

    ID of the thread

  • commentId required

    ID of the comment

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/threads/{threadId}/comments/{commentId}/remove-reaction
{  "emoji": "👨‍👩‍👧",  "userId": "alice",  "removedAt": "2022-07-13T14:32:50.697Z"}

Notifications

get/users/:userId/inboxNotifications/:inboxNotificationId

Get inbox notificationBeta

This endpoint returns a user’s inbox notification by its ID. Corresponds to liveblocks.getInboxNotification.

Parameters

  • roomId required

    ID of the room

  • inboxNotificationId required

    ID of the inbox notification

Request

GET
https://api.liveblocks.io/v2/users/{userId}/inboxNotifications/{inboxNotificationId}

Response

Status:
{  "id": {    "type": "string"  },  "kind": {    "type": "string",    "default": "thread"  },  "threadId": {    "type": "string"  },  "readAt": {    "type": "string",    "format": "date-time"  },  "notifiedAt": {    "type": "string",    "format": "date-time"  }}
get/rooms/:roomId/users/:userId/notification-settings

Get room notification settingsBeta

This endpoint returns a user’s notification settings for a specific room. Corresponds to liveblocks.getRoomNotificationSettings.

Parameters

  • roomId required

    ID of the room

  • userId required

    ID of the user

Request

GET
https://api.liveblocks.io/v2/rooms/{roomId}/users/{userId}/notification-settings

Response

Status:
{  "threads": {    "enum": [      "all",      "replies_and_mentions",      "none"    ]  }}
post/rooms/:roomId/users/:userId/notification-settings

Update room notification settingsBeta

This endpoint updates a user’s notification settings for a specific room. Corresponds to liveblocks.updateRoomNotificationSettings.

Parameters

  • roomId required

    ID of the room

  • userId required

    ID of the user

Request body

POST
https://api.liveblocks.io/v2/rooms/{roomId}/users/{userId}/notification-settings
{  "threads": {    "enum": [      "all",      "replies_and_mentions",      "none"    ]  }}

Response

Status:
{  "threads": {    "enum": [      "all",      "replies_and_mentions",      "none"    ]  }}
delete/rooms/:roomId/users/:userId/notification-settings

Delete room notification settingsBeta

This endpoint deletes a user’s notification settings for a specific room. Corresponds to liveblocks.deleteRoomNotificationSettings.

Parameters

  • roomId required

    ID of the room

  • userId required

    ID of the user

Request

DELETE
https://api.liveblocks.io/v2/rooms/{roomId}/users/{userId}/notification-settings

Deprecated

Deprecated. Prefer using access tokens or ID tokens instead. Read more in our migration guide.

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.

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.

Parameters

  • roomId required

    ID of the room

Request body

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

Response

Status:

Success. Returns an old-style single-room token.

{  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}
post/rooms/:roomId/public/authorize

Get single-room token with public keyDeprecated

Deprecated. When you update Liveblocks to 1.2, you no longer need to get a JWT token when using a public key.

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"]).

Parameters

  • roomId required

    ID of the room

Request body

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