--- title: "Create a new room" method: POST path: "/_matrix/client/v3/createRoom" tags: ["Room creation"] --- # Create a new room `POST /_matrix/client/v3/createRoom` ## Request - Base URL: `https://matrix.org` - URL: `https://matrix.org/_matrix/client/v3/createRoom` - Auth: one of: - API key in query parameter `access_token` - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Create a new room with various configuration options. The server MUST apply the normal state resolution rules when creating the new room, including checking power levels for each event. It MUST apply the events implied by the request in the following order: 1. The `m.room.create` event itself. Must be the first event in the room. 2. An `m.room.member` event for the creator to join the room. This is needed so the remaining events can be sent. 3. A default `m.room.power_levels` event. Overridden by the `power_level_content_override` parameter. In [room versions](https://spec.matrix.org/v1.19/rooms) 1 through 11, the room creator (and not other members) will be given permission to send state events. In room versions 12 and later, the room creator is given infinite power level and cannot be specified in the `users` field of `m.room.power_levels`, so is not listed explicitly. **Note**: For `trusted_private_chat`, the users specified in the `invite` parameter SHOULD also be appended to `additional_creators` by the server, per the `creation_content` parameter. If the room's version is 12 or higher, the power level for sending `m.room.tombstone` events MUST explicitly be higher than `state_default`. For example, set to 150 instead of 100. 4. An `m.room.canonical_alias` event if `room_alias_name` is given. 5. Events set by the `preset`. Currently these are the `m.room.join_rules`, `m.room.history_visibility`, and `m.room.guest_access` state events. 6. Events listed in `initial_state`, in the order that they are listed. 7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` state events). 8. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with `membership: invite` and `m.room.third_party_invite`). The available presets do the following with respect to room state: | Preset | `join_rules` | `history_visibility` | `guest_access` | Other | |------------------------|--------------|----------------------|----------------|-------| | `private_chat` | `invite` | `shared` | `can_join` | | | `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. | | `public_chat` | `public` | `shared` | `forbidden` | | The server will create a `m.room.create` event in the room with the requesting user as the creator, alongside other keys provided in the `creation_content` or implied by behaviour of `creation_content`. ## Request body - object - `creation_content` object: Extra keys, such as `m.federate`, to be added to the content of the [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate) event. The server will overwrite the following keys: `creator`, `room_version`. Future versions of the specification may allow the server to overwrite other keys. When using the `trusted_private_chat` preset, the server SHOULD combine `additional_creators` specified here and the `invite` array into the eventual `m.room.create` event's `additional_creators`, deduplicating between the two parameters. - `initial_state` object[]: A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set. Takes precedence over events set by `preset`, but gets overridden by `name` and `topic` keys. - `content` object, required: The content of the event. - `state_key` string: The state_key of the state event. Defaults to an empty string. - `type` string, required: The type of event to send. - `invite` string[]: A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room. - `invite_3pid` object[]: A list of objects representing third-party IDs to invite into the room. - `address` string, required: The invitee's third-party identifier. - `id_access_token` string, required: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version. - `id_server` string, required: The hostname+port of the identity server which should be used for third-party identifier lookups. - `medium` string, required: The kind of address being passed in the address field, for example `email` (see [the list of recognised values](https://spec.matrix.org/v1.19/appendices/#3pid-types)). - `is_direct` boolean: This flag makes the server set the `is_direct` flag on the `m.room.member` events sent to the users in `invite` and `invite_3pid`. See [Direct Messaging](https://spec.matrix.org/v1.19/client-server-api/#direct-messaging) for more information. - `name` string: If this is included, an [`m.room.name`](https://spec.matrix.org/v1.19/client-server-api/#mroomname) event will be sent into the room to indicate the name for the room. This overwrites any [`m.room.name`](https://spec.matrix.org/v1.19/client-server-api/#mroomname) event in `initial_state`. - `power_level_content_override` object: The power level content to override in the default power level event. This object is applied on top of the generated [`m.room.power_levels`](https://spec.matrix.org/v1.19/client-server-api/#mroompower_levels) event content prior to it being sent to the room. Defaults to overriding nothing. - `preset` 'private_chat' | 'public_chat' | 'trusted_private_chat': Convenience parameter for setting various default state events based on a preset. If unspecified, the server should use the `visibility` to determine which preset to use. A visibility of `public` equates to a preset of `public_chat` and `private` visibility equates to a preset of `private_chat`. - `room_alias_name` string: The desired room alias **local part**. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the *same* homeserver which created the room. For example, if this was set to "foo" and sent to the homeserver "example.com" the complete room alias would be `#foo:example.com`. The complete room alias will become the canonical alias for the room and an `m.room.canonical_alias` event will be sent into the room. - `room_version` string: The room version to set for the room. If not provided, the homeserver is to use its configured default. If provided, the homeserver will return a 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not support the room version. - `topic` string: If this is included, an [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic) event with a `text/plain` mimetype will be sent into the room to indicate the topic for the room. This overwrites any [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic) event in `initial_state`. - `visibility` 'public' | 'private': The room's visibility in the server's [published room directory](https://spec.matrix.org/v1.19/client-server-api#published-room-directory). Defaults to `private`. ## Response `200` Information about the newly created room. - object: Information about the newly created room. - `room_id` string, mx-room-id, required: The created room's ID. ## Other responses - `400`: The request is invalid. A meaningful `errcode` and description error text will be returned. Example reasons for rejection include: - The request body is malformed (`errcode` set to `M_BAD_JSON` or `M_NOT_JSON`). - The room alias specified is already taken (`errcode` set to `M_ROOM_IN_USE`). - The initial state implied by the parameters to the request is invalid: for example, the user's `power_level` is set below that necessary to set the room name (`errcode` set to `M_INVALID_ROOM_STATE`). - The homeserver doesn't support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. - `403`: Creating the room is not allowed. **[Added in `v1.18`]** The `M_INVITE_BLOCKED` error code is used to indicate that one of the homeservers of the invited users rejected the invite due to [invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission). --- [API](https://skmtc.dev/matrix/apis/matrix-client-server-api.md) - [All operations](https://skmtc.dev/matrix/apis/matrix-client-server-api/llms.txt) - [OpenAPI document](https://skmtc.dev/matrix/apis/matrix-client-server-api/revisions/c7fe4072c681?raw)