Liveblocks Python SDK
The Python SDK for Liveblocks provides you with a client for accessing Liveblocks APIs. This library is complementary to the front end libraries provided by Liveblocks.
Installation
Install the Liveblocks package to get started.
pip install liveblocks
Quickstart
All API calls require a Liveblocks client set up with your secret key. Find your key in the Liveblocks Dashboard.
Synchronous
from liveblocks import Liveblocks
client = Liveblocks(secret="{{SECRET_KEY}}")
with client:
rooms = client.get_rooms()
print(rooms)
Asynchronous
from liveblocks import AsyncLiveblocks
client = AsyncLiveblocks(secret="{{SECRET_KEY}}")
async with client:
rooms = await client.get_rooms()
print(rooms)
API Reference
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.
Example
result = client.get_rooms(
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
# organization_id="org_123456789",
# query="metadata[\"color\"]:\"blue\"",
# user_id="user-123",
# group_ids="group1,group2",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
limit |
int | Unset |
No | A limit on the number of rooms to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
organization_id |
str | Unset |
No | A filter on organization ID. |
query |
str | Unset |
No | Query to filter rooms. You can filter by roomId and metadata, for example, metadata["roomType"]:"whiteboard" AND roomId^"liveblocks:engineering". Learn more about filtering rooms with query language. |
user_id |
str | Unset |
No | A filter on users accesses. |
group_ids |
str | Unset |
No | A filter on groups accesses. Multiple groups can be used. |
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.
defaultAccessesis the default room permission list, for example[],["*:read"],["*:write"], or a more granular permission list.metadatacould be key/value asstringorstring[].metadatasupports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 256 characters maximum.metadatais optional field.usersAccessescontains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters.usersAccessesis optional field.groupsAccessescontains group-specific permission lists and is optional.
Example
from liveblocks.models import CreateRoomRequestBody
result = client.create_room(
body=CreateRoomRequestBody(
id="...",
default_accesses=[],
# organization_id="...",
# users_accesses=...,
# groups_accesses=...,
),
# idempotent=True,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
idempotent |
bool | Unset |
No | When provided, will not return a 409 when the room already exists, but instead return the existing room as-is. Corresponds to liveblocks.getOrCreateRoom. |
body |
CreateRoomRequestBody |
Yes | Request body (application/json) |
get_room
This endpoint returns a room by its ID. Corresponds to liveblocks.getRoom.
Example
result = client.get_room(
room_id="my-room-id",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of 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 } }
defaultAccesses, metadata, usersAccesses, groupsAccesses can be updated.
defaultAccessesis the default room permission list, for example[],["*:read"],["*:write"], or a more granular permission list.metadatacould be key/value asstringorstring[].metadatasupports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 256 characters maximum.metadatais optional field.usersAccessescontains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters.usersAccessesis optional field.groupsAccessescontains group-specific permission lists and is optional.
Example
from liveblocks.models import UpdateRoomRequestBody
result = client.update_room(
room_id="my-room-id",
body=UpdateRoomRequestBody(
# default_accesses=[],
# users_accesses=...,
# groups_accesses=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
UpdateRoomRequestBody |
Yes | Request body (application/json) |
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.
Example
client.delete_room(
room_id="my-room-id",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
prewarm_room
Speeds up connecting to a room for the next 10 seconds. Use this when you know a user will be connecting to a room with RoomProvider or enterRoom within 10 seconds, and the room will load quicker. Corresponds to liveblocks.prewarmRoom.
Example
client.prewarm_room(
room_id="my-room-id",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
upsert_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 } }
defaultAccesses, metadata, usersAccesses, groupsAccesses can be updated.
defaultAccessesis the default room permission list, for example[],["*:read"],["*:write"], or a more granular permission list.metadatacould be key/value asstringorstring[].metadatasupports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 256 characters maximum.metadatais optional field.usersAccessescontains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters.usersAccessesis optional field.groupsAccessescontains group-specific permission lists and is optional.
Example
from liveblocks.models import UpsertRoomRequestBody
result = client.upsert_room(
room_id="my-room-id",
body=UpsertRoomRequestBody(
update=...,
# create=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
UpsertRoomRequestBody |
Yes | Request body (application/json) |
update_room_id
This endpoint permanently updates the room’s ID. All existing references to the old room ID will need to be updated. Returns the updated room. Corresponds to liveblocks.updateRoomId.
Example
from liveblocks.models import UpdateRoomIdRequestBody
result = client.update_room_id(
room_id="my-room-id",
body=UpdateRoomIdRequestBody(
new_room_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | The new ID for the room |
body |
UpdateRoomIdRequestBody |
Yes | Request body (application/json) |
update_room_organization_id
This endpoint updates the room's organization ID. The fromOrganizationId must match the room's current organization ID. Returns the updated room.
Example
from liveblocks.models import UpdateRoomOrganizationIdRequestBody
result = client.update_room_organization_id(
room_id="my-room-id",
body=UpdateRoomOrganizationIdRequestBody(
from_organization_id="...",
to_organization_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | The ID of the room |
body |
UpdateRoomOrganizationIdRequestBody |
Yes | Request body (application/json) |
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.
Example
result = client.get_active_users(
room_id="my-room-id",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
set_presence
This endpoint sets ephemeral presence for a user in a room without requiring a WebSocket connection. The presence data will automatically expire after the specified TTL (time-to-live). This is useful for scenarios like showing an AI agent's presence in a room. The presence will be broadcast to all connected users in the room. Corresponds to liveblocks.setPresence.
Example
from liveblocks.models import SetPresenceRequestBody
client.set_presence(
room_id="my-room-id",
body=SetPresenceRequestBody(
user_id="...",
data=...,
user_info=...,
# ttl=0,
),
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
SetPresenceRequestBody |
Yes | Request body (application/json) |
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. The connectionId passed to event listeners is -1 when using this API. Corresponds to liveblocks.broadcastEvent.
Example
client.broadcast_event(
room_id="my-room-id",
body=...,
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
Any |
Yes | Request body (application/json) |
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.
Example
result = client.get_storage_document(
room_id="my-room-id",
# format_=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
format_ |
GetStorageDocumentFormat | Unset |
No | Use the json format to output a simplified JSON representation of the Storage tree. In that format, each LiveObject and LiveMap becomes a simple JSON object, each LiveList becomes a simple JSON array, and each LiveFile becomes its metadata object. This is a lossy format because information about the original data structures is not retained, but it may be easier to work with. |
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" | "LiveFile""data"=> contains the nested data structures (children) and data.
The root’s type can only be LiveObject.
A utility function, toPlainLson is included in @liveblocks/client from 1.0.9 to help convert LiveObject, LiveList, LiveMap, and LiveFile to the structure expected by the endpoint.
Example
from liveblocks.models import InitializeStorageDocumentBody
result = client.initialize_storage_document(
room_id="my-room-id",
body=InitializeStorageDocumentBody(
liveblocks_type=...,
data=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
InitializeStorageDocumentBody |
Yes | Request body (application/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.
Example
client.delete_storage_document(
room_id="my-room-id",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
patch_storage_document
Applies a sequence of JSON Patch operations to the room's Storage document, useful for modifying Storage. Operations are applied in order; if any operation fails, the document is not changed and a 422 response with a helpful message is returned.
Paths and data types: Be as specific as possible with your target path. Every parent in the chain of path segments must be a LiveObject, LiveList, or LiveMap. Complex nested objects passed in add or replace operations are automatically converted to LiveObjects and LiveLists.
Performance: For large Storage documents, applying a patch can be expensive because the full state is reconstructed on the server to apply the operations. Very large documents may not be suitable for this endpoint.
For a full guide with examples, see Modifying storage via REST API with JSON Patch.
Example
client.patch_storage_document(
room_id="my-room-id",
body=...,
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
list[AddJsonPatchOperation | CopyJsonPatchOperation | MoveJsonPatchOperation | RemoveJsonPatchOperation | ReplaceJsonPatchOperation | TestJsonPatchOperation] |
Yes | Request body (application/json) |
get_storage_file
Returns an uploaded Storage file's metadata and a presigned download URL. The URL expires after one hour.
Example
result = client.get_storage_file(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID of the Storage file |
upload_storage_file
Uploads a file's bytes to a room and returns the metadata needed to create a LiveFile. For large files, use the multipart upload operations instead. Repeating the request with the same file ID, name, and file size returns the existing upload.
Example
result = client.upload_storage_file(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
name="photo.png",
body=...,
# file_size=12345,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID for the Storage file |
name |
str |
Yes | Name of the file |
file_size |
int | Unset |
No | Expected file size in bytes. |
body |
File |
Yes | Request body (application/octet-stream) |
create_storage_file_multipart_upload
Starts a multipart upload for a Storage file.
Example
result = client.create_storage_file_multipart_upload(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
name="video.mp4",
# file_size=10485760,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID for the Storage file |
name |
str |
Yes | Name of the file |
file_size |
int | Unset |
No | Expected file size in bytes |
upload_storage_file_multipart_part
Uploads one part of a Storage file multipart upload.
Example
result = client.upload_storage_file_multipart_part(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
upload_id="...",
part_number=1,
body=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID of the Storage file |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
part_number |
int |
Yes | One-based part number |
body |
File |
Yes | Request body (application/octet-stream) |
complete_storage_file_multipart_upload
Completes a multipart upload and returns the metadata needed to create a LiveFile.
Example
from liveblocks.models import CompleteStorageFileMultipartUploadRequestBody
result = client.complete_storage_file_multipart_upload(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
upload_id="...",
body=CompleteStorageFileMultipartUploadRequestBody(
parts=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID of the Storage file |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
body |
CompleteStorageFileMultipartUploadRequestBody |
Yes | Request body (application/json) |
abort_storage_file_multipart_upload
Aborts a multipart upload and discards its uploaded parts.
Example
client.abort_storage_file_multipart_upload(
room_id="my-room-id",
file_id="fl_abc123456789012345678",
upload_id="...",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
file_id |
str |
Yes | ID of the Storage file |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
Yjs
get_yjs_document
This endpoint returns a JSON representation of the room’s Yjs document. Corresponds to liveblocks.getYjsDocument.
Example
result = client.get_yjs_document(
room_id="my-room-id",
# formatting=True,
# key="root",
# type_=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
formatting |
bool | Unset |
No | If present, YText will return formatting. |
key |
str | Unset |
No | Returns only a single key’s value, e.g. doc.get(key).toJSON(). |
type_ |
GetYjsDocumentType | Unset |
No | Used with key to override the inferred type, i.e. "ymap" will return doc.get(key, Y.Map). |
send_yjs_binary_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.
Example
client.send_yjs_binary_update(
room_id="my-room-id",
body=...,
# guid="subdoc-guid-123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
guid |
str | Unset |
No | ID of the subdocument |
body |
File |
Yes | Request body (application/octet-stream) |
get_yjs_document_as_binary_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.
Example
result = client.get_yjs_document_as_binary_update(
room_id="my-room-id",
# guid="subdoc-guid-123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
guid |
str | Unset |
No | ID of the subdocument |
Version_history
get_version_history
This endpoint returns a list of version history snapshots for the room. The versions are returned sorted by creation date, from newest to oldest. Corresponds to liveblocks.getVersionHistory.
Example
result = client.get_version_history(
room_id="my-room-id",
# limit=20,
# cursor="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
limit |
int | Unset |
No | A limit on the number of versions to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
cursor |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
create_version_history_snapshot
This endpoint creates a new version history snapshot of the room, capturing both its Storage and Yjs documents. Corresponds to liveblocks.createVersionHistorySnapshot.
Example
result = client.create_version_history_snapshot(
room_id="my-room-id",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
get_yjs_version
This endpoint returns a specific version of the room's Yjs document encoded as a binary Yjs update. Corresponds to liveblocks.getYjsVersion.
Example
result = client.get_yjs_version(
room_id="my-room-id",
version_id="vh_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
version_id |
str |
Yes | ID of the version |
delete_version
This endpoint permanently deletes a version from the room's history. Corresponds to liveblocks.deleteVersion.
Example
client.delete_version(
room_id="my-room-id",
version_id="vh_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
version_id |
str |
Yes | ID of the version |
Comments
get_threads
This endpoint returns the threads in the requested room. Corresponds to liveblocks.getThreads.
Example
result = client.get_threads(
room_id="my-room-id",
# query="metadata[\"color\"]:\"blue\"",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
query |
str | Unset |
No | Query to filter threads. You can filter by metadata, resolved, and visibility, for example, metadata["status"]:"open" AND metadata["color"]:"red" AND resolved:true AND visibility:"private". Learn more about filtering threads with query language. |
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.
{
"version": 1,
"content": [
{
"type": "paragraph",
"children": [{ "text": "Hello " }, { "text": "world", "bold": true }]
}
]
}
metadata supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 4000 characters maximum for strings.
Example
from liveblocks.models import CreateThreadRequestBody
result = client.create_thread(
room_id="my-room-id",
body=CreateThreadRequestBody(
comment=...,
# metadata=...,
# visibility=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
CreateThreadRequestBody |
Yes | Request body (application/json) |
get_thread
This endpoint returns a thread by its ID. Corresponds to liveblocks.getThread.
Example
result = client.get_thread(
room_id="my-room-id",
thread_id="th_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
delete_thread
This endpoint deletes a thread by its ID. Corresponds to liveblocks.deleteThread.
Example
client.delete_thread(
room_id="my-room-id",
thread_id="th_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
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.
metadata supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 4000 characters maximum for strings.
Example
from liveblocks.models import EditThreadMetadataRequestBody
result = client.edit_thread_metadata(
room_id="my-room-id",
thread_id="th_abc123",
body=EditThreadMetadataRequestBody(
metadata=...,
user_id="...",
# updated_at=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
EditThreadMetadataRequestBody |
Yes | Request body (application/json) |
mark_thread_as_resolved
This endpoint marks a thread as resolved. The request body must include a userId to identify who resolved the thread. Returns the updated thread. Corresponds to liveblocks.markThreadAsResolved.
Example
from liveblocks.models import MarkThreadAsResolvedRequestBody
result = client.mark_thread_as_resolved(
room_id="my-room-id",
thread_id="th_abc123",
body=MarkThreadAsResolvedRequestBody(
user_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
MarkThreadAsResolvedRequestBody |
Yes | Request body (application/json) |
mark_thread_as_unresolved
This endpoint marks a thread as unresolved. The request body must include a userId to identify who unresolved the thread. Returns the updated thread. Corresponds to liveblocks.markThreadAsUnresolved.
Example
from liveblocks.models import MarkThreadAsUnresolvedRequestBody
result = client.mark_thread_as_unresolved(
room_id="my-room-id",
thread_id="th_abc123",
body=MarkThreadAsUnresolvedRequestBody(
user_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
MarkThreadAsUnresolvedRequestBody |
Yes | Request body (application/json) |
subscribe_to_thread
This endpoint subscribes to a thread. Corresponds to liveblocks.subscribeToThread.
Example
from liveblocks.models import SubscribeToThreadRequestBody
result = client.subscribe_to_thread(
room_id="my-room-id",
thread_id="th_abc123",
body=SubscribeToThreadRequestBody(
user_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
SubscribeToThreadRequestBody |
Yes | Request body (application/json) |
unsubscribe_from_thread
This endpoint unsubscribes from a thread. Corresponds to liveblocks.unsubscribeFromThread.
Example
from liveblocks.models import UnsubscribeFromThreadRequestBody
client.unsubscribe_from_thread(
room_id="my-room-id",
thread_id="th_abc123",
body=UnsubscribeFromThreadRequestBody(
user_id="...",
),
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
UnsubscribeFromThreadRequestBody |
Yes | Request body (application/json) |
get_thread_subscriptions
This endpoint gets the list of subscriptions to a thread. Corresponds to liveblocks.getThreadSubscriptions.
Example
result = client.get_thread_subscriptions(
room_id="my-room-id",
thread_id="th_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
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.
{
"version": 1,
"content": [
{
"type": "paragraph",
"children": [{ "text": "Hello " }, { "text": "world", "bold": true }]
}
]
}
metadata supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 4000 characters maximum for strings.
Example
from liveblocks.models import CreateCommentRequestBody
result = client.create_comment(
room_id="my-room-id",
thread_id="th_abc123",
body=CreateCommentRequestBody(
user_id="...",
body=...,
# created_at=...,
# metadata=...,
# attachment_ids=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
body |
CreateCommentRequestBody |
Yes | Request body (application/json) |
get_comment
This endpoint returns a comment by its ID. Corresponds to liveblocks.getComment.
Example
result = client.get_comment(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the 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.
{
"version": 1,
"content": [
{
"type": "paragraph",
"children": [{ "text": "Hello " }, { "text": "world", "bold": true }]
}
]
}
Example
from liveblocks.models import EditCommentRequestBody
result = client.edit_comment(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
body=EditCommentRequestBody(
body=...,
# edited_at=...,
# metadata=...,
# attachment_ids=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the comment |
body |
EditCommentRequestBody |
Yes | Request body (application/json) |
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.
Example
client.delete_comment(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the comment |
add_comment_reaction
This endpoint adds a reaction to a comment. Corresponds to liveblocks.addCommentReaction.
Example
from liveblocks.models import AddCommentReactionRequestBody
result = client.add_comment_reaction(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
body=AddCommentReactionRequestBody(
user_id="...",
emoji="...",
# created_at=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the comment |
body |
AddCommentReactionRequestBody |
Yes | Request body (application/json) |
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.
Example
from liveblocks.models import RemoveCommentReactionRequestBody
client.remove_comment_reaction(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
body=RemoveCommentReactionRequestBody(
user_id="...",
emoji="...",
# removed_at=...,
),
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the comment |
body |
RemoveCommentReactionRequestBody |
Yes | Request body (application/json) |
get_attachment
Gets an attachment's metadata and a presigned download URL. The URL expires after 1 hour.
Example
result = client.get_attachment(
room_id="my-room-id",
attachment_id="at_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID of the attachment |
upload_attachment
Uploads a file's bytes and returns a draft comment attachment. Pass the returned attachment ID in the comment's attachment IDs when creating or editing a comment. For large files, use the multipart upload operations instead.
Example
result = client.upload_attachment(
room_id="my-room-id",
attachment_id="at_abc123456789012345678",
name="screenshot.png",
user_id="alice",
body=...,
# file_size=12345,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID for the attachment |
name |
str |
Yes | Name of the file |
user_id |
str |
Yes | ID of the user uploading the attachment |
file_size |
int | Unset |
No | Expected file size in bytes |
body |
File |
Yes | Request body (application/octet-stream) |
create_attachment_multipart_upload
Starts a multipart upload for a draft comment attachment.
Example
result = client.create_attachment_multipart_upload(
room_id="my-room-id",
attachment_id="at_abc123456789012345678",
name="recording.mp4",
# file_size=10485760,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID for the attachment |
name |
str |
Yes | Name of the file |
file_size |
int | Unset |
No | Expected file size in bytes |
upload_attachment_multipart_part
Uploads one part of an attachment multipart upload.
Example
result = client.upload_attachment_multipart_part(
room_id="my-room-id",
attachment_id="at_abc123456789012345678",
upload_id="...",
part_number=1,
body=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID of the attachment |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
part_number |
int |
Yes | One-based part number |
body |
File |
Yes | Request body (application/octet-stream) |
complete_attachment_multipart_upload
Completes a multipart upload and returns a draft comment attachment. Pass the returned attachment ID in the comment's attachment IDs when creating or editing a comment.
Example
from liveblocks.models import CompleteAttachmentMultipartUploadRequestBody
result = client.complete_attachment_multipart_upload(
room_id="my-room-id",
attachment_id="at_abc123456789012345678",
upload_id="...",
user_id="alice",
body=CompleteAttachmentMultipartUploadRequestBody(
parts=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID of the attachment |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
user_id |
str |
Yes | ID of the user uploading the attachment |
body |
CompleteAttachmentMultipartUploadRequestBody |
Yes | Request body (application/json) |
abort_attachment_multipart_upload
Aborts a multipart upload and discards its uploaded parts.
Example
client.abort_attachment_multipart_upload(
room_id="my-room-id",
attachment_id="at_abc123456789012345678",
upload_id="...",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
attachment_id |
str |
Yes | ID of the attachment |
upload_id |
str |
Yes | ID returned when the multipart upload was created |
edit_comment_metadata
This endpoint edits the metadata of a comment. The metadata is a JSON object that can be used to store any information you want about the comment, in string, number, or boolean form. Set a property to null to remove it. Corresponds to liveblocks.editCommentMetadata.
metadata supports maximum 50 entries. Key length has a limit of 40 characters maximum. Value length has a limit of 4000 characters maximum for strings.
Example
from liveblocks.models import EditCommentMetadataRequestBody
result = client.edit_comment_metadata(
room_id="my-room-id",
thread_id="th_abc123",
comment_id="cm_abc123",
body=EditCommentMetadataRequestBody(
metadata=...,
user_id="...",
# updated_at=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
comment_id |
str |
Yes | ID of the comment |
body |
EditCommentMetadataRequestBody |
Yes | Request body (application/json) |
get_thread_inbox_notifications
This endpoint returns the inbox notifications associated with a specific thread. Because this endpoint is not user-scoped, each notification includes a userId field identifying which user the notification belongs to. Only thread-kind notifications are returned.
Example
result = client.get_thread_inbox_notifications(
room_id="my-room-id",
thread_id="th_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
thread_id |
str |
Yes | ID of the thread |
Feeds
get_feeds
This endpoint returns the feeds in the requested room. Corresponds to liveblocks.getFeeds.
Example
result = client.get_feeds(
room_id="my-room-id",
# cursor="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
# since=1660000988137,
# limit=20,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
cursor |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
since |
int | Unset |
No | Only return feeds with createdAt greater than this Unix timestamp in milliseconds. |
limit |
int | Unset |
No | A limit on the number of feeds to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
create_feed
This endpoint creates a new feed in a room. Corresponds to liveblocks.createFeed.
Example
from liveblocks.models import CreateFeedRequestBody
result = client.create_feed(
room_id="my-room-id",
body=CreateFeedRequestBody(
feed_id="...",
# metadata=...,
# timestamp=0.0,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
body |
CreateFeedRequestBody |
Yes | Request body (application/json) |
get_feed
This endpoint returns a feed by its ID. Corresponds to liveblocks.getFeed.
Example
result = client.get_feed(
room_id="my-room-id",
feed_id="fd_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
delete_feed
This endpoint deletes a feed. Corresponds to liveblocks.deleteFeed.
Example
client.delete_feed(
room_id="my-room-id",
feed_id="fd_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
update_feed
This endpoint updates the metadata of a feed. Corresponds to liveblocks.updateFeed.
Example
from liveblocks.models import UpdateFeedRequestBody
result = client.update_feed(
room_id="my-room-id",
feed_id="fd_abc123",
body=UpdateFeedRequestBody(
metadata=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
body |
UpdateFeedRequestBody |
Yes | Request body (application/json) |
get_feed_messages
This endpoint returns the messages in a feed. Corresponds to liveblocks.getFeedMessages.
Example
result = client.get_feed_messages(
room_id="my-room-id",
feed_id="fd_abc123",
# cursor="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
# since=1660000988137,
# limit=20,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
cursor |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
since |
int | Unset |
No | Only return messages with createdAt greater than this Unix timestamp in milliseconds. |
limit |
int | Unset |
No | A limit on the number of messages to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
create_feed_message
This endpoint creates a new message in a feed. Corresponds to liveblocks.createFeedMessage.
Example
from liveblocks.models import CreateFeedMessageRequestBody
result = client.create_feed_message(
room_id="my-room-id",
feed_id="fd_abc123",
body=CreateFeedMessageRequestBody(
data=...,
# id="...",
# timestamp=0.0,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
body |
CreateFeedMessageRequestBody |
Yes | Request body (application/json) |
delete_feed_message
This endpoint deletes a feed message. Corresponds to liveblocks.deleteFeedMessage.
Example
client.delete_feed_message(
room_id="my-room-id",
feed_id="fd_abc123",
message_id="msg_xyz789",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
message_id |
str |
Yes | ID of the message |
update_feed_message
This endpoint updates a feed message. Corresponds to liveblocks.updateFeedMessage.
Example
from liveblocks.models import UpdateFeedMessageRequestBody
result = client.update_feed_message(
room_id="my-room-id",
feed_id="fd_abc123",
message_id="msg_xyz789",
body=UpdateFeedMessageRequestBody(
data=...,
# timestamp=0.0,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
feed_id |
str |
Yes | ID of the feed |
message_id |
str |
Yes | ID of the message |
body |
UpdateFeedMessageRequestBody |
Yes | Request body (application/json) |
Auth
authorize_user
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.
Example
from liveblocks.models import AuthorizeUserRequestBody
result = client.authorize_user(
body=AuthorizeUserRequestBody(
user_id="...",
permissions=...,
# user_info=...,
# organization_id="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
body |
AuthorizeUserRequestBody |
Yes | Request body (application/json) |
identify_user
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.
Example
from liveblocks.models import IdentifyUserRequestBody
result = client.identify_user(
body=IdentifyUserRequestBody(
user_id="...",
# organization_id="...",
# group_ids=[],
# user_info=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
body |
IdentifyUserRequestBody |
Yes | Request body (application/json) |
Notifications
get_inbox_notification
This endpoint returns a user’s inbox notification by its ID. Corresponds to liveblocks.getInboxNotification.
Example
result = client.get_inbox_notification(
user_id="user-123",
inbox_notification_id="in_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
inbox_notification_id |
str |
Yes | ID of the inbox notification |
delete_inbox_notification
This endpoint deletes a user’s inbox notification by its ID. Corresponds to liveblocks.deleteInboxNotification.
Example
client.delete_inbox_notification(
user_id="user-123",
inbox_notification_id="in_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
inbox_notification_id |
str |
Yes | ID of the inbox notification |
get_inbox_notifications
This endpoint returns all the user’s inbox notifications. Corresponds to liveblocks.getInboxNotifications.
Example
result = client.get_inbox_notifications(
user_id="user-123",
# organization_id="org_123456789",
# query="metadata[\"color\"]:\"blue\"",
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
organization_id |
str | Unset |
No | The organization ID to filter notifications for. |
query |
str | Unset |
No | Query to filter notifications. You can filter by unread, for example, unread:true. |
limit |
int | Unset |
No | A limit on the number of inbox notifications to be returned. The limit can range between 1 and 50, and defaults to 50. (default: 50) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
delete_all_inbox_notifications
This endpoint deletes all the user’s inbox notifications. Corresponds to liveblocks.deleteAllInboxNotifications.
Example
client.delete_all_inbox_notifications(
user_id="user-123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
get_notification_settings
This endpoint returns a user's notification settings for the project. Corresponds to liveblocks.getNotificationSettings.
Example
result = client.get_notification_settings(
user_id="user-123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
update_notification_settings
This endpoint updates a user's notification settings for the project. Corresponds to liveblocks.updateNotificationSettings.
Example
from liveblocks.models import UpdateNotificationSettingsRequestBody
result = client.update_notification_settings(
user_id="user-123",
body=UpdateNotificationSettingsRequestBody(
# email=...,
# slack=...,
# teams=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
body |
UpdateNotificationSettingsRequestBody |
Yes | Request body (application/json) |
delete_notification_settings
This endpoint deletes a user's notification settings for the project. Corresponds to liveblocks.deleteNotificationSettings.
Example
client.delete_notification_settings(
user_id="user-123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
get_room_subscription_settings
This endpoint returns a user’s subscription settings for a specific room. Corresponds to liveblocks.getRoomSubscriptionSettings.
Example
result = client.get_room_subscription_settings(
room_id="my-room-id",
user_id="user-123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
user_id |
str |
Yes | ID of the user |
update_room_subscription_settings
This endpoint updates a user’s subscription settings for a specific room. Corresponds to liveblocks.updateRoomSubscriptionSettings.
Example
from liveblocks.models import UpdateRoomSubscriptionSettingsRequestBody
result = client.update_room_subscription_settings(
room_id="my-room-id",
user_id="user-123",
body=UpdateRoomSubscriptionSettingsRequestBody(
# threads=...,
# text_mentions=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
user_id |
str |
Yes | ID of the user |
body |
UpdateRoomSubscriptionSettingsRequestBody |
Yes | Request body (application/json) |
delete_room_subscription_settings
This endpoint deletes a user’s subscription settings for a specific room. Corresponds to liveblocks.deleteRoomSubscriptionSettings.
Example
client.delete_room_subscription_settings(
room_id="my-room-id",
user_id="user-123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
room_id |
str |
Yes | ID of the room |
user_id |
str |
Yes | ID of the user |
get_user_room_subscription_settings
This endpoint returns the list of a user's room subscription settings. Corresponds to liveblocks.getUserRoomSubscriptionSettings.
Example
result = client.get_user_room_subscription_settings(
user_id="user-123",
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
# limit=20,
# organization_id="org_123456789",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | ID of the user |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
limit |
int | Unset |
No | A limit on the number of elements to be returned. The limit can range between 1 and 50, and defaults to 50. (default: 50) |
organization_id |
str | Unset |
No | The organization ID to filter room subscription settings for. |
trigger_inbox_notification
This endpoint triggers an inbox notification. Corresponds to liveblocks.triggerInboxNotification.
Example
from liveblocks.models import TriggerInboxNotificationRequestBody
client.trigger_inbox_notification(
body=TriggerInboxNotificationRequestBody(
user_id="...",
kind="...",
subject_id="...",
activity_data=...,
# room_id="...",
# organization_id="...",
),
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
body |
TriggerInboxNotificationRequestBody |
Yes | Request body (application/json) |
mark_inbox_notification_as_read
This endpoint marks a specific inbox notification as read.
Example
client.mark_inbox_notification_as_read(
inbox_notification_id="in_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
inbox_notification_id |
str |
Yes | ID of the inbox notification |
Groups
get_groups
This endpoint returns a list of all groups in your project. Corresponds to liveblocks.getGroups.
Example
result = client.get_groups(
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
limit |
int | Unset |
No | A limit on the number of groups to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
create_group
This endpoint creates a new group. Corresponds to liveblocks.createGroup.
Example
from liveblocks.models import CreateGroupRequestBody
result = client.create_group(
body=CreateGroupRequestBody(
id="...",
# member_ids=[],
# organization_id="...",
# scopes=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
body |
CreateGroupRequestBody |
Yes | Request body (application/json) |
get_group
This endpoint returns a specific group by ID. Corresponds to liveblocks.getGroup.
Example
result = client.get_group(
group_id="engineering",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
str |
Yes | The ID of the group to retrieve. |
delete_group
This endpoint deletes a group. Corresponds to liveblocks.deleteGroup.
Example
client.delete_group(
group_id="engineering",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
str |
Yes | The ID of the group to delete. |
add_group_members
This endpoint adds new members to an existing group. Corresponds to liveblocks.addGroupMembers.
Example
from liveblocks.models import AddGroupMembersRequestBody
result = client.add_group_members(
group_id="engineering",
body=AddGroupMembersRequestBody(
member_ids=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
str |
Yes | The ID of the group to add members to. |
body |
AddGroupMembersRequestBody |
Yes | Request body (application/json) |
remove_group_members
This endpoint removes members from an existing group. Corresponds to liveblocks.removeGroupMembers.
Example
from liveblocks.models import RemoveGroupMembersRequestBody
result = client.remove_group_members(
group_id="engineering",
body=RemoveGroupMembersRequestBody(
member_ids=[],
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
group_id |
str |
Yes | The ID of the group to remove members from. |
body |
RemoveGroupMembersRequestBody |
Yes | Request body (application/json) |
get_user_groups
This endpoint returns all groups that a specific user is a member of. Corresponds to liveblocks.getUserGroups.
Example
result = client.get_user_groups(
user_id="user-123",
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
user_id |
str |
Yes | The ID of the user to get groups for. |
limit |
int | Unset |
No | A limit on the number of groups to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
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.
Example
result = client.get_ai_copilots(
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
limit |
int | Unset |
No | A limit on the number of copilots to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
create_ai_copilot
This endpoint creates a new AI copilot with the given configuration. Corresponds to liveblocks.createAiCopilot.
Example
result = client.create_ai_copilot(
body=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
body |
CreateAiCopilotOptionsAnthropic | CreateAiCopilotOptionsGoogle | CreateAiCopilotOptionsOpenAi | CreateAiCopilotOptionsOpenAiCompatible |
Yes | Request body (application/json) |
get_ai_copilot
This endpoint returns an AI copilot by its ID. Corresponds to liveblocks.getAiCopilot.
Example
result = client.get_ai_copilot(
copilot_id="cp_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
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.
Example
from liveblocks.models import UpdateAiCopilotRequestBody
result = client.update_ai_copilot(
copilot_id="cp_abc123",
body=UpdateAiCopilotRequestBody(
# name="...",
# description="...",
# system_prompt="...",
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
body |
UpdateAiCopilotRequestBody |
Yes | Request body (application/json) |
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.
Example
client.delete_ai_copilot(
copilot_id="cp_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
get_knowledge_sources
This endpoint returns a paginated list of knowledge sources for a specific AI copilot. Corresponds to liveblocks.getKnowledgeSources.
Example
result = client.get_knowledge_sources(
copilot_id="cp_abc123",
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
limit |
int | Unset |
No | A limit on the number of knowledge sources to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
get_knowledge_source
This endpoint returns a specific knowledge source by its ID. Corresponds to liveblocks.getKnowledgeSource.
Example
result = client.get_knowledge_source(
copilot_id="cp_abc123",
knowledge_source_id="ks_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
knowledge_source_id |
str |
Yes | ID of the knowledge source |
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.
Example
from liveblocks.models import CreateWebKnowledgeSourceRequestBody
result = client.create_web_knowledge_source(
copilot_id="cp_abc123",
body=CreateWebKnowledgeSourceRequestBody(
copilot_id="...",
url="...",
type_=...,
),
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
body |
CreateWebKnowledgeSourceRequestBody |
Yes | Request body (application/json) |
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.
Example
result = client.create_file_knowledge_source(
copilot_id="cp_abc123",
name="document.pdf",
body=...,
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
name |
str |
Yes | Name of the file |
body |
File |
Yes | Request body (application/octet-stream) |
get_file_knowledge_source_markdown
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.
Example
result = client.get_file_knowledge_source_markdown(
copilot_id="cp_abc123",
knowledge_source_id="ks_abc123",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
knowledge_source_id |
str |
Yes | ID of the 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.
Example
client.delete_file_knowledge_source(
copilot_id="cp_abc123",
knowledge_source_id="ks_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
knowledge_source_id |
str |
Yes | ID of the knowledge source |
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.
Example
client.delete_web_knowledge_source(
copilot_id="cp_abc123",
knowledge_source_id="ks_abc123",
)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
knowledge_source_id |
str |
Yes | ID of the knowledge source |
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.
Example
result = client.get_web_knowledge_source_links(
copilot_id="cp_abc123",
knowledge_source_id="ks_abc123",
# limit=20,
# starting_after="eyJjcmVhdGVkQXQiOjE2NjAwMDA5ODgxMzd9",
)
print(result)
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
copilot_id |
str |
Yes | ID of the AI copilot |
knowledge_source_id |
str |
Yes | ID of the knowledge source |
limit |
int | Unset |
No | A limit on the number of links to be returned. The limit can range between 1 and 100, and defaults to 20. (default: 20) |
starting_after |
str | Unset |
No | A cursor used for pagination. Get the value from the nextCursor response of the previous page. |
Error Handling
All API methods raise errors.LiveblocksError when the server returns a non-2xx status code. You can catch and inspect these errors:
from liveblocks import errors, Liveblocks
client = Liveblocks(secret="sk_your_secret_key")
with client:
try:
room = client.get_room(room_id="my-room")
except errors.LiveblocksError as e:
print(f"API error: {e}")
Methods also raise httpx.TimeoutException if the request exceeds the timeout.
1 maintainer
Metadata
1 maintainer
Release files for liveblocks 3.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| liveblocks-3.23.0.tar.gz | 123.4 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| liveblocks-3.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 422.8 kB
Release files / liveblocks-3.23.0.tar.gz
| Download URL | liveblocks-3.23.0.tar.gz |
|---|---|
| Size | 123.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9eb0f884bd4b3fd5438ead674294ca113902ee3447260c7fb101d56bf1344e8e
|
|
BLAKE2b-256 checksum How to use checksums |
33766149a193a5ea76c72b7c0560ae441ca50c6ec8b4627718a81697a2530432
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / liveblocks-3.23.0-py3-none-any.whl
| Download URL | liveblocks-3.23.0-py3-none-any.whl |
|---|---|
| Size | 299.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c71e11278134e7dcc722775cda9431b97fe698ebc6357fa5875eb782343f4a33
|
|
BLAKE2b-256 checksum How to use checksums |
2c5f27dabdf1d13b0191201c9d19a9a68eba5494ee6c083828093ec13752ee2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for liveblocks 3.23.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
