matrix-spec/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.
swagger: '2.0'
info:
  title: "Matrix Client-Server Room Creation API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
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:

        0. A default ``m.room.power_levels`` event, giving the room creator
           (and not other members) permission to send state events.
        
        1. Events set by the ``preset``.

        2. Events listed in ``initial_state``, in the order that they are
           listed.

        3. Events implied by ``name`` and ``topic``.

        4. Invite events implied by ``invite`` and ``invite_3pid``.

        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``     
        ========================  ==============  ======================  ================  =========

      operationId: createRoom
      security:
        - accessToken: []
      parameters:
        - in: body
          name: body
          description: The desired room configuration.
          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: |-
                  A ``public`` visibility indicates that the room will be shown
                  in the published room list. A ``private`` visibility will hide
                  the room from the published room list. Rooms default to
                  ``private`` visibility if this key is not included. NB: This
                  should not be confused with ``join_rules`` which also uses the
                  word ``public``.
              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``.
              name:
                type: string
                description: |-
                  If this is included, an ``m.room.name`` event will be sent
                  into the room to indicate the name of the room. See Room
                  Events for more information on ``m.room.name``.
              topic:
                type: string
                description: |-
                  If this is included, an ``m.room.topic`` event will be sent
                  into the room to indicate the topic for the room. See Room
                  Events for more information on ``m.room.topic``.
              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:
                  type: object
                  title: Invite3pid
                  properties:
                    id_server:
                      type: string
                      description: The hostname+port of the identity server which should be used for third party identifier lookups.
                    medium:
                      type: string
                      # TODO: Link to identity service spec when it eixsts
                      description: The kind of address being passed in the address field, for example ``email``.
                    address:
                      type: string
                      description: The invitee's third party identifier.
                  required: ["id_server", "medium", "address"]
              creation_content:
                title: CreationContent
                type: object
                description: |-
                  Extra keys to be added to the content of the ``m.room.create``.
                  The server will clobber the following keys: ``creator``. Future
                  versions of the specification may allow the server to clobber
                  other keys.
              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
                  overriden 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.
              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`_ for more information.
              guest_can_join:
                type: boolean
                description: |-
                  Allows guests to join the room. See `Guest Access`_ for more information.
      responses:
        200:
          description: Information about the newly created room.
          schema:
            type: object
            description: Information about the newly created room.
            properties:
              room_id:
                type: string
                description: |-
                  The created room's ID.
          examples:
            application/json: {
                "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``).
          schema:
            "$ref": "definitions/errors/error.yaml"

      tags:
        - Room creation