How to filter rooms using query language

When retrieving rooms with our REST API, it’s possible to filter for specific rooms using custom metadata and room ID prefixes using our custom query language. This enables the Get Rooms REST API to have filtering that works the same as with liveblocks.getRooms.

Query language

You can filter rooms by their metadata and room ID prefixes, which is helpful when you’re using a naming pattern for your rooms. Filters can be combined using AND logic.

// Rooms with IDs that begin with "liveblocks:"roomId^'liveblocks:'
// Rooms with { roomType: 'whiteboard' } string metadatametadata['roomType']:'whiteboard'
// Combine queries with ANDroomId^'liveblocks:' AND metadata['roomType']:'whiteboard'
// Use multiple metadata filters at oncemetadata['roomType']:'whiteboard' AND metadata['creator']:'florent'

Note that room metadata can contain strings or arrays, but only strings can be filtered. If you wish to return a single specific room, instead use the Get Room API or liveblocks.getRoom.

You can also filter rooms by whether they contain threads:

hasThreads:true

Use hasThreads:false to return rooms with no threads, and hasThreads:"unresolved" or hasThreads:"resolved" to return rooms with at least one thread in that state. Deleted threads are excluded. Rooms with both resolved and unresolved threads match either filter. You can combine these filters with room metadata:

hasThreads:"unresolved" AND metadata["roomType"]:"whiteboard"

How to use

To use the query language with the REST API pass your query string to the query parameter. For example, given this query:

roomId^'liveblocks:' AND metadata['roomType']:'whiteboard'

Encode it, and add it to the query parameter:

https://api.liveblocks.io/v2/rooms?query=roomId%5E'liveblocks%3A'%20AND%20metadata%5B'roomType'%5D%3A'whiteboard'

To learn more on setting custom metadata on rooms, make sure to read our guide.