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 update 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.
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
Response
Success. Returns an access token that can be used to enter one or more rooms.
Get ID token with secret key
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
Response
Success. Returns an ID token that can be used to enter one or more rooms.
Room
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 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
.
Parameters
limit
optionalA 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
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.tenantId
optionalA filter on tenant ID.
query
optionalQuery to filter rooms. You can filter by
roomId
andmetadata
, 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.
Request
Response
Success. Returns the list of rooms, the next page cursor, and the next page URL.
Create room
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.
defaultAccessess
could be[]
or["room:write"]
(private or public).metadata
could be key/value asstring
orstring[]
.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
Response
Success. Returns the created room.
Get room
This endpoint returns a room by its ID. Corresponds to liveblocks.getRoom
.
Parameters
roomId
requiredID of the room
Request
Response
Success. Returns the room.
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 asstring
orstring[]
.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
requiredID of the room
Request body
Response
Success. Returns the updated room.
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
requiredID of the room
Request
Upsert (update or create) room
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 } }
defaultAccessess
, metadata
, usersAccesses
, groupsAccesses
can be updated.
defaultAccessess
could be[]
or["room:write"]
(private or public).metadata
could be key/value asstring
orstring[]
.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
requiredID of the room
Request body
Response
Success. Returns the updated or created room.
Update room ID
This endpoint permanently updates the room’s ID.
Parameters
roomId
requiredThe new ID for the room
Request body
Response
Success. Returns the updated room with the new ID.
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
requiredID of the room
Request
Response
Success. Returns the list of active users for the specified room.
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
requiredID of the room
Request body
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:
If you’re not interested in this information, you can use the simpler ?format=json
query param, see below.
Parameters
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.
Request
Response
Success. Returns the room’s Storage as JSON.
Initialize Storage document
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.
Parameters
roomId
requiredID of the room
Request body
Response
Success. The Storage is initialized. Returns the room’s Storage as JSON.
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
requiredID of the room
Request
Yjs
Get Yjs document
This endpoint returns a JSON representation of the room’s Yjs document. Corresponds to liveblocks.getYjsDocument
.
Parameters
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 returndoc.get(key, Y.Map)
.
Request
Response
Success. Returns the room’s Yjs document as JSON.
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
requiredID of the room
guid
optionalID of the subdocument
Request body
Response
Success. The given room’s Yjs doc has been updated.
Get Yjs document encoded as a binary Yjs update
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
requiredID of the room
guid
optionalID of the subdocument
Request
Schema validation
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
Response
Success. Creates the new schema and returns it as JSON.
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
requiredID of the schema
Request
Response
Success. Found the schema and returns it as JSON.
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
requiredID of the schema
Request body
Response
Success. Updates the new schema and increments the version. The schema body
is returned as JSON.
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
requiredID of the schema
Request
Get schema by room ID
This endpoint retrieves the schema attached to a room. Corresponds to liveblocks.getSchemaByRoomId
.
Parameters
roomId
requiredID of the room
Request
Response
Success. Found the schema attached to the room and returns it as JSON.
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
requiredID of the room
Request body
Response
Success. Found the schema attached to the room. Returns the schema ID as JSON.
Detach schema from room
This endpoint detaches the schema from a room. Corresponds to liveblocks.detachSchemaFromRoom
.
Parameters
roomId
requiredID of the room
Request
Comments
Get room threads
This endpoint returns the threads in the requested room. Corresponds to liveblocks.getThreads
.
Parameters
roomId
requiredID of the room
query
optionalQuery to filter threads. You can filter by
metadata
andresolved
, for example,metadata["status"]:"open" AND metadata["color"]:"red" AND resolved:true
. Learn more about filtering threads with query language.
Request
Response
Success. Returns list of threads in a room.
Create thread
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
.
Parameters
roomId
requiredID of the room
Request body
Response
Success. Returns the created thread.
Get thread
This endpoint returns a thread by its ID. Corresponds to liveblocks.getThread
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success. Returns requested thread.
Delete thread
This endpoint deletes a thread by its ID. Corresponds to liveblocks.deleteThread
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Edit thread metadata
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
requiredID of the room
threadId
requiredID of the thread
Request body
Response
Success. Returns the updated metadata.
Mark thread as resolved
This endpoint marks a thread as resolved.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success. Returns the updated thread.
Mark thread as unresolved
This endpoint marks a thread as unresolved.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success. Returns the updated thread.
Subscribe to thread
This endpoint subscribes to a thread. Corresponds to liveblocks.subscribeToThread
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success. Returns the thread subscription.
Unsubscribe from thread
This endpoint unsubscribes from a thread. Corresponds to liveblocks.unsubscribeFromThread
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success.
Get thread subscriptions
This endpoint gets the list of subscriptions to a thread. Corresponds to liveblocks.getThreadSubscriptions
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success.
Create comment
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
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
Request body
Response
Success. Returns the created comment.
Get comment
This endpoint returns a comment by its ID. Corresponds to liveblocks.getComment
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Request
Response
Success. Returns the requested comment.
Edit 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
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Request body
Response
Success. Returns the edited comment.
Delete 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
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Request
Add comment reaction
This endpoint adds a reaction to a comment. Corresponds to liveblocks.addCommentReaction
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Request body
Response
Success. Returns the created reaction.
Remove comment 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
.
Parameters
roomId
requiredID of the room
threadId
requiredID of the thread
commentId
requiredID of the comment
Request body
Notifications
Get inbox notification
This endpoint returns a user’s inbox notification by its ID. Corresponds to liveblocks.getInboxNotification
.
Parameters
userId
requiredID of the user
inboxNotificationId
requiredID of the inbox notification
Request
Response
Delete inbox notification
This endpoint deletes a user’s inbox notification by its ID.
Parameters
userId
requiredID of the user
inboxNotificationId
requiredID of the inbox notification
Request
Delete all inbox notifications
This endpoint deletes all the user’s inbox notifications.
Parameters
userId
requiredID of the user
Request
Get all inbox notifications
This endpoint returns all the user’s inbox notifications. Corresponds to liveblocks.getInboxNotifications
.
Parameters
userId
requiredID of the user
tenantId
optionalThe tenant ID to filter notifications for.
query
optionalQuery to filter notifications. You can filter by
unread
, for example,unread:true
.limit
optionalA limit on the number of inbox notifications to be returned. The limit can range between 1 and 50, and defaults to 50.
- Minimum: 1
- Maximum: 50
- Default: 50
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
Response
Get notification settings
This endpoint returns a user's notification settings for the project. Corresponds to liveblocks.getNotificationSettings
.
Parameters
userId
requiredID of the user
Request
Response
Update notification settings
This endpoint updates a user's notification settings for the project. Corresponds to liveblocks.updateNotificationSettings
.
Parameters
userId
requiredID of the user
Request body
Response
Delete notification settings
This endpoint deletes a user's notification settings for the project. Corresponds to liveblocks.deleteNotificationSettings
.
Parameters
userId
requiredID of the user
Request
Get room subscription settings
This endpoint returns a user’s subscription settings for a specific room. Corresponds to liveblocks.getRoomSubscriptionSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user
Request
Response
Update room subscription settings
This endpoint updates a user’s subscription settings for a specific room. Corresponds to liveblocks.updateRoomSubscriptionSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user
Request body
Response
Delete room subscription settings
This endpoint deletes a user’s subscription settings for a specific room. Corresponds to liveblocks.deleteRoomSubscriptionSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user
Request
Get user room subscription settings
This endpoint returns the list of a user's room subscription settings. Corresponds to liveblocks.getUserRoomSubscriptionSettings
.
Parameters
userId
requiredID of the user
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.limit
optionalA limit on the number of elements to be returned. The limit can range between 1 and 50, and defaults to 50.
- Minimum: 1
- Maximum: 50
- Default: 50
Request
Response
Trigger inbox notification
This endpoint triggers an inbox notification. Corresponds to liveblocks.triggerInboxNotification
.
Request body
Groups
Create group
This endpoint creates a new group. Corresponds to liveblocks.createGroup
.
Request body
Get groups
This endpoint returns a list of all groups in your project. Corresponds to liveblocks.getGroups
.
Parameters
limit
optionalA limit on the number of groups to be returned. The limit can range between 1 and 100, and defaults to 20.
- Minimum: 1
- Maximum: 100
- Default: 20
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
Get group
This endpoint returns a specific group by ID. Corresponds to liveblocks.getGroup
.
Parameters
groupId
requiredThe ID of the group to retrieve.
Request
Delete group
This endpoint deletes a group. Corresponds to liveblocks.deleteGroup
.
Parameters
groupId
requiredThe ID of the group to delete.
Request
Add group members
This endpoint adds new members to an existing group. Corresponds to liveblocks.addGroupMembers
.
Parameters
groupId
requiredThe ID of the group to add members to.
Request body
Remove group members
This endpoint removes members from an existing group. Corresponds to liveblocks.removeGroupMembers
.
Parameters
groupId
requiredThe ID of the group to remove members from.
Request body
Get user groups
This endpoint returns all groups that a specific user is a member of. Corresponds to liveblocks.getUserGroups
.
Parameters
userId
requiredThe ID of the user to get groups for.
limit
optionalA limit on the number of groups to be returned. The limit can range between 1 and 100, and defaults to 20.
- Minimum: 1
- Maximum: 100
- Default: 20
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
AI
Get AI copilots
This endpoint returns a paginated list of AI copilots. The copilots are returned sorted by creation date, from newest to oldest. Corresponds to liveblocks.getAiCopilots
.
Parameters
limit
optionalA limit on the number of copilots to be returned. The limit can range between 1 and 100, and defaults to 20.
- Minimum: 1
- Maximum: 100
- Default: 20
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
Response
Success. Returns the list of AI copilots.
Create AI copilot
This endpoint creates a new AI copilot with the given configuration. Corresponds to liveblocks.createAiCopilot
.
Request body
Get AI copilot
This endpoint returns an AI copilot by its ID. Corresponds to liveblocks.getAiCopilot
.
Parameters
copilotId
requiredID of the AI copilot
Request
Update AI copilot
This endpoint updates an existing AI copilot's configuration. Corresponds to liveblocks.updateAiCopilot
.
This endpoint returns a 422 response if the update doesn't apply due to validation failures. For example, if the existing copilot uses the "openai" provider and you attempt to update the provider model to an incompatible value for the provider, like "gemini-2.5-pro", you'll receive a 422 response with an error message explaining where the validation failed.
Parameters
copilotId
requiredID of the AI copilot
Request body
Delete AI copilot
This endpoint deletes an AI copilot by its ID. A deleted copilot is no longer accessible and cannot be restored. Corresponds to liveblocks.deleteAiCopilot
.
Parameters
copilotId
requiredID of the AI copilot
Request
Get knowledge sources
This endpoint returns a paginated list of knowledge sources for a specific AI copilot. Corresponds to liveblocks.getKnowledgeSources
.
Parameters
copilotId
requiredID of the AI copilot
limit
optionalA limit on the number of knowledge sources to be returned. The limit can range between 1 and 100, and defaults to 20.
- Minimum: 1
- Maximum: 100
- Default: 20
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
Response
Success. Returns the list of knowledge sources.
Get knowledge source
This endpoint returns a specific knowledge source by its ID. Corresponds to liveblocks.getKnowledgeSource
.
Parameters
copilotId
requiredID of the AI copilot
knowledgeSourceId
requiredID of the knowledge source
Request
Create web knowledge source
This endpoint creates a web knowledge source for an AI copilot. This allows the copilot to access and learn from web content. Corresponds to liveblocks.createWebKnowledgeSource
.
Parameters
copilotId
requiredID of the AI copilot
Request body
Response
Success. Returns the ID of the created knowledge source.
Create file knowledge source
This endpoint creates a file knowledge source for an AI copilot by uploading a file. The copilot can then reference the content of the file when responding. Corresponds to liveblocks.createFileKnowledgeSource
.
Parameters
copilotId
requiredID of the AI copilot
name
requiredName of the file
Request body
Response
Success. Returns the ID of the created knowledge source.
Get file knowledge source content
This endpoint returns the content of a file knowledge source as Markdown. This allows you to see what content the AI copilot has access to from uploaded files. Corresponds to liveblocks.getFileKnowledgeSourceMarkdown
.
Parameters
copilotId
requiredID of the AI copilot
knowledgeSourceId
requiredID of the knowledge source
Request
Response
Success. Returns the content of the file knowledge source.
Delete file knowledge source
This endpoint deletes a file knowledge source from an AI copilot. The copilot will no longer have access to the content from this file. Corresponds to liveblocks.deleteFileKnowledgeSource
.
Parameters
copilotId
requiredID of the AI copilot
knowledgeSourceId
requiredID of the knowledge source
Request
Delete web knowledge source
This endpoint deletes a web knowledge source from an AI copilot. The copilot will no longer have access to the content from this source. Corresponds to liveblocks.deleteWebKnowledgeSource
.
Parameters
copilotId
requiredID of the AI copilot
knowledgeSourceId
requiredID of the knowledge source
Request
Get web knowledge source links
This endpoint returns a paginated list of links that were indexed from a web knowledge source. This is useful for understanding what content the AI copilot has access to from web sources. Corresponds to liveblocks.getWebKnowledgeSourceLinks
.
Parameters
copilotId
requiredID of the AI copilot
knowledgeSourceId
requiredID of the knowledge source
limit
optionalA limit on the number of links to be returned. The limit can range between 1 and 100, and defaults to 20.
- Minimum: 1
- Maximum: 100
- Default: 20
startingAfter
optionalA cursor used for pagination. Get the value from the
nextCursor
response of the previous page.
Request
Response
Success. Returns the list of web knowledge source links.
Deprecated
Get thread participantsDeprecated
Deprecated. Prefer using thread subscriptions instead.
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
requiredID of the room
threadId
requiredID of the thread
Request
Response
Success. Returns the thread’s participants
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
requiredID of the room
Request body
Response
Success. Returns an old-style single-room token.
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
requiredID of the room
Request body
Response
Success. Returns the JWT token.
Get room notification settingsDeprecated
Deprecated. Renamed to /subscription-settings
. Read more in our migration guide.
This endpoint returns a user’s subscription settings for a specific room. Corresponds to liveblocks.getRoomNotificationSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user
Request
Response
Update room notification settingsDeprecated
Deprecated. Renamed to /subscription-settings
. Read more in our migration guide.
This endpoint updates a user’s notification settings for a specific room. Corresponds to liveblocks.updateRoomNotificationSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user
Request body
Response
Delete room notification settingsDeprecated
Deprecated. Renamed to /subscription-settings
. Read more in our migration guide.
This endpoint deletes a user’s notification settings for a specific room. Corresponds to liveblocks.deleteRoomNotificationSettings
.
Parameters
roomId
requiredID of the room
userId
requiredID of the user