matrix-spec/data/api/client-server/create_room.yaml

# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
openapi: 3.1.0
info:
  title: Matrix Client-Server Room Creation API
  version: 1.0.0
paths:
  /createRoom:
    post:
      summary: Create a new room
      description: |-
        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](/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`.
      operationId: createRoom
      x-changedInMatrixVersion:
        "1.16": Added server behaviour for how the initial power levels change depending on room version.
      security:
        - accessTokenQuery: []
        - accessTokenBearer: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {
                "preset": "public_chat",
                "room_alias_name": "thepub",
                "name": "The Grand Duke Pub",
                "topic": "All about happy hour",
                "creation_content": {
                  "m.federate": false
                }
              }
              properties:
                visibility:
                  type: string
                  enum:
                    - public
                    - private
                  description: |-
                    The room's visibility in the server's
                    [published room directory](/client-server-api#published-room-directory).
                    Defaults to `private`.
                room_alias_name:
                  type: string
                  description: |-
                    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.
                name:
                  type: string
                  description: |-
                    If this is included, an [`m.room.name`](/client-server-api/#mroomname) event
                    will be sent into the room to indicate the name for the room.
                    This overwrites any [`m.room.name`](/client-server-api/#mroomname)
                    event in `initial_state`.
                topic:
                  type: string
                  description: |-
                    If this is included, an [`m.room.topic`](/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`](/client-server-api/#mroomtopic) event in `initial_state`.
                invite:
                  type: array
                  description: |-
                    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.
                  items:
                    type: string
                invite_3pid:
                  type: array
                  description: |-
                    A list of objects representing third-party IDs to invite into
                    the room.
                  items:
                    $ref: definitions/invite_3pid.yaml
                room_version:
                  type: string
                  description: |-
                    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.
                  example: "1"
                creation_content:
                  title: CreationContent
                  type: object
                  x-changedInMatrixVersion:
                    "1.16": Added server behaviour for how to handle `trusted_private_chat` and invited users.
                  description: |-
                    Extra keys, such as `m.federate`, to be added to the content
                    of the [`m.room.create`](/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:
                  type: array
                  description: |-
                    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.
                  items:
                    type: object
                    title: StateEvent
                    properties:
                      type:
                        type: string
                        description: The type of event to send.
                      state_key:
                        type: string
                        description: The state_key of the state event. Defaults to an empty string.
                      content:
                        type: object
                        description: The content of the event.
                    required:
                      - type
                      - content
                preset:
                  type: string
                  enum:
                    - private_chat
                    - public_chat
                    - trusted_private_chat
                  description: |-
                    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`.
                is_direct:
                  type: boolean
                  description: |-
                    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](/client-server-api/#direct-messaging) for more information.
                power_level_content_override:
                  title: Power Level Event Content
                  type: object
                  description: |-
                    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`](/client-server-api/#mroompower_levels)
                    event content prior to it being sent to the room. Defaults to
                    overriding nothing.
        description: The desired room configuration.
        required: true
      responses:
        "200":
          description: Information about the newly created room.
          content:
            application/json:
              schema:
                type: object
                description: Information about the newly created room.
                properties:
                  room_id:
                    type: string
                    description: The created room's ID.
                required:
                  - room_id
              examples:
                response:
                  value: {
                    "room_id": "!sefiuhWgwghwWgh:example.com"
                  }
        "400":
          description: |-

            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.
          content:
            application/json:
              schema:
                $ref: definitions/errors/error.yaml
      tags:
        - Room creation
servers:
  - url: "{protocol}://{hostname}{basePath}"
    variables:
      protocol:
        enum:
          - http
          - https
        default: https
      hostname:
        default: localhost:8008
      basePath:
        default: /_matrix/client/v3
components:
  securitySchemes:
    accessTokenQuery:
      $ref: definitions/security.yaml#/accessTokenQuery
    accessTokenBearer:
      $ref: definitions/security.yaml#/accessTokenBearer