How to filter rooms using query language

When retrieving rooms with our REST API, it’s possible to filter for specific threads 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.

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.