Sign in
Room

Create room

Changed on

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.

  • defaultAccesses is the default room permission list, for example [], ["*:read"], ["*:write"], or a more granular permission list.
  • metadata could be key/value as string or string[]. 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 contains user-specific permission lists. It can contain 1000 ids maximum. Id length has a limit of 256 characters. usersAccesses is optional field.
  • groupsAccesses contains group-specific permission lists and is optional.
post/rooms

Request

  • Base URL: https://api.liveblocks.io/v2
  • URL: https://api.liveblocks.io/v2/rooms
  • Auth: none declared

Query parameters

idempotentboolean

When provided, will not return a 409 when the room already exists, but instead return the existing room as-is. Corresponds to liveblocks.getOrCreateRoom.

Example:true

Request body

idstring required
organizationIdstring

The organization ID to associate with the room. Defaults to "default" if not provided.

defaultAccessesRoomPermissionItem[] required
usersAccessesRoomAccesses
groupsAccessesRoomAccesses
metadataRoomMetadata
engine1 | 2

Preferred storage engine version to use when creating new rooms. The v2 Storage engine supports larger documents, is more performant, has native streaming support, and will become the default in the future.

Example request

{
  "id": "my-room-id",
  "defaultAccesses": [
    "*:write"
  ],
  "metadata": {
    "color": "blue"
  },
  "usersAccesses": {
    "alice": [
      "*:write"
    ]
  },
  "groupsAccesses": {
    "product": [
      "*:write"
    ]
  }
}

Response

Success. Returns the created room.

idstring required
type'room' required
organizationIdstring required

The organization ID associated with this room.

lastConnectionAtstring date-time
createdAtstring date-time required
defaultAccessesRoomPermissionItem[] required
usersAccessesRoomAccesses required
groupsAccessesRoomAccesses required
metadataRoomMetadata required

Example response

{
  "type": "room",
  "id": "my-room-id",
  "lastConnectionAt": "2022-08-04T21:07:09.380Z",
  "createdAt": "2022-07-13T14:32:50.697Z",
  "organizationId": "org_123456789",
  "metadata": {
    "color": "blue",
    "type": "whiteboard"
  },
  "defaultAccesses": [
    "*:write"
  ],
  "groupsAccesses": {
    "marketing": [
      "*:write"
    ]
  },
  "usersAccesses": {
    "alice": [
      "*:write"
    ]
  }
}

Changes

  • e66e044110f9Revision changes
    • warning

      added the new comments:private:none enum value to the / response property for the response status

    • warning

      added the new comments:private:none enum value to the // response property for the response status

    • warning

      added the new comments:private:none enum value to the // response property for the response status

    • warning

      added the new comments:private:read enum value to the / response property for the response status

    • warning

      added the new comments:private:read enum value to the // response property for the response status

    • warning

      added the new comments:private:read enum value to the // response property for the response status

    • warning

      added the new comments:private:write enum value to the / response property for the response status

    • warning

      added the new comments:private:write enum value to the // response property for the response status

    • warning

      added the new comments:private:write enum value to the // response property for the response status

    • warning

      added the new comments:public:none enum value to the / response property for the response status

    • warning

      added the new comments:public:none enum value to the // response property for the response status

    • warning

      added the new comments:public:none enum value to the // response property for the response status

    • warning

      added the new comments:public:read enum value to the / response property for the response status

    • warning

      added the new comments:public:read enum value to the // response property for the response status

    • warning

      added the new comments:public:read enum value to the // response property for the response status

    • warning

      added the new comments:public:write enum value to the / response property for the response status

    • warning

      added the new comments:public:write enum value to the // response property for the response status

    • warning

      added the new comments:public:write enum value to the // response property for the response status

    • info

      added the new comments:private:none enum value to the request property /

    • info

      added the new comments:private:none enum value to the request property //

    • info

      added the new comments:private:none enum value to the request property //

    • info

      added the new comments:private:read enum value to the request property /

    • info

      added the new comments:private:read enum value to the request property //

    • info

      added the new comments:private:read enum value to the request property //

    • info

      added the new comments:private:write enum value to the request property /

    • info

      added the new comments:private:write enum value to the request property //

    • info

      added the new comments:private:write enum value to the request property //

    • info

      added the new comments:public:none enum value to the request property /

    • info

      added the new comments:public:none enum value to the request property //

    • info

      added the new comments:public:none enum value to the request property //

    • info

      added the new comments:public:read enum value to the request property /

    • info

      added the new comments:public:read enum value to the request property //

    • info

      added the new comments:public:read enum value to the request property //

    • info

      added the new comments:public:write enum value to the request property /

    • info

      added the new comments:public:write enum value to the request property //

    • info

      added the new comments:public:write enum value to the request property //

  • f7ddea756395Revision changes
    • warning

      added the new *:read enum value to the / response property for the response status

    • warning

      added the new *:read enum value to the // response property for the response status

    • warning

      added the new *:read enum value to the // response property for the response status

    • warning

      added the new *:write enum value to the / response property for the response status

    • warning

      added the new *:write enum value to the // response property for the response status

    • warning

      added the new *:write enum value to the // response property for the response status

    • warning

      added the new comments:none enum value to the / response property for the response status

    • warning

      added the new comments:none enum value to the // response property for the response status

    • warning

      added the new comments:none enum value to the // response property for the response status

    • warning

      added the new comments:read enum value to the / response property for the response status

    • warning

      added the new comments:read enum value to the // response property for the response status

    • warning

      added the new comments:read enum value to the // response property for the response status

    • warning

      added the new feeds:none enum value to the / response property for the response status

    • warning

      added the new feeds:none enum value to the // response property for the response status

    • warning

      added the new feeds:none enum value to the // response property for the response status

    • warning

      added the new feeds:read enum value to the / response property for the response status

    • warning

      added the new feeds:read enum value to the // response property for the response status

    • warning

      added the new feeds:read enum value to the // response property for the response status

    • warning

      added the new feeds:write enum value to the / response property for the response status

    • warning

      added the new feeds:write enum value to the // response property for the response status

    • warning

      added the new feeds:write enum value to the // response property for the response status

    • warning

      added the new storage:none enum value to the / response property for the response status

    • warning

      added the new storage:none enum value to the // response property for the response status

    • warning

      added the new storage:none enum value to the // response property for the response status

    • warning

      added the new storage:read enum value to the / response property for the response status

    • warning

      added the new storage:read enum value to the // response property for the response status

    • warning

      added the new storage:read enum value to the // response property for the response status

    • warning

      added the new storage:write enum value to the / response property for the response status

    • warning

      added the new storage:write enum value to the // response property for the response status

    • warning

      added the new storage:write enum value to the // response property for the response status

    • info

      added the new *:read enum value to the request property /

    • info

      added the new *:read enum value to the request property //

    • info

      added the new *:read enum value to the request property //

    • info

      added the new *:write enum value to the request property /

    • info

      added the new *:write enum value to the request property //

    • info

      added the new *:write enum value to the request property //

    • info

      added the new comments:none enum value to the request property /

    • info

      added the new comments:none enum value to the request property //

    • info

      added the new comments:none enum value to the request property //

    • info

      added the new comments:read enum value to the request property /

    • info

      added the new comments:read enum value to the request property //

    • info

      added the new comments:read enum value to the request property //

    • info

      added the new feeds:none enum value to the request property /

    • info

      added the new feeds:none enum value to the request property //

    • info

      added the new feeds:none enum value to the request property //

    • info

      added the new feeds:read enum value to the request property /

    • info

      added the new feeds:read enum value to the request property //

    • info

      added the new feeds:read enum value to the request property //

    • info

      added the new feeds:write enum value to the request property /

    • info

      added the new feeds:write enum value to the request property //

    • info

      added the new feeds:write enum value to the request property //

    • info

      added the new storage:none enum value to the request property /

    • info

      added the new storage:none enum value to the request property //

    • info

      added the new storage:none enum value to the request property //

    • info

      added the new storage:read enum value to the request property /

    • info

      added the new storage:read enum value to the request property //

    • info

      added the new storage:read enum value to the request property //

    • info

      added the new storage:write enum value to the request property /

    • info

      added the new storage:write enum value to the request property //

    • info

      added the new storage:write enum value to the request property //