API Reference – API v1 Endpoints

Manage a room and its storage using the Liveblocks REST API endpoints. They’ll help you manage your data and extend Liveblocks’ functionality. You’ll find the API base URL below.

$https://liveblocks.net/api/v1/

Authentication

To use the API, you need to add a JWT token to the request’s authorization header:

$curl https://liveblocks.net/api/v1/* \  -H "Authorization: Bearer YOUR_JWT_TOKEN"

You can get a JWT token by calling our authorization endpoint, using your secret key (accessible from the dashboard). The token will be valid for one hour.

$curl https://liveblocks.io/api/authorize \  -H "Authorization: Bearer YOUR_SECRET_KEY"

Example response

{ "token": "YOUR_JWT_TOKEN" }

Get room storage

Get the room storage data as a JSON using the endpoint below.

https://liveblocks.net/api/v1/room/:roomId/storage

Some implementation details

• Each Liveblocks data structure is represented by a JSON element having two properties:
  • "liveblocksType": "LiveObject" | "LiveList" | "LiveMap"
  • "data" => contains the nested data structures (children) and data.
• The root is always a LiveObject.

Example response

{  "liveblocksType": "LiveObject",  "data": {    "aLiveObject": {      "liveblocksType": "LiveObject",      "data": {        "a": 1      }    },    "aLiveList": {      "liveblocksType": "LiveList",      "data": ["a", "b"]    },    "aLiveMap": {      "liveblocksType": "LiveMap",      "data": {        "a": 1,        "b": 2      }    }  }}

Initialize room storage

Initialize a room storage using the following endpoint. The storage of the room you’re initializing must be empty. The new storage data can be passed as a JSON in the request body.

https://liveblocks.net/api/v1/room/:roomId/storage

Some implementation details

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

Example request body

{  "liveblocksType": "LiveObject",  "data": {    "aLiveObject": {      "liveblocksType": "LiveObject",      "data": {        "a": 1      }    },    "aLiveList": {      "liveblocksType": "LiveList",      "data": ["a", "b"]    },    "aLiveMap": {      "liveblocksType": "LiveMap",      "data": {        "a": 1,        "b": 2      }    }  }}

Delete room storage

Delete all elements of the room storage using the following endpoint.

https://liveblocks.net/api/v1/room/:roomId/storage

Get room users

Get the current list of users connected to a room.

https://liveblocks.net/api/v1/room/:roomId/users

Some implementation details

• User's custom properties id and info can be set during the authentication to the room, see authorize.

Example response

{  "data": [    {      "type": "user",      "connectionId": 0,      "id": "customUserId",      "info": {}    }  ]}