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

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.
      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 clober 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 ``presets``, but gets
                  overriden by ``name`` and ``topic`` keys.
                items:
                  type: object
                  title: StateEvent
                  properties:
                    type:
                      type: string
                    state_key:
                      type: string
                    content:
                      type: string
              preset:
                type: string
                enum: ["private_chat", "public_chat", "trusted_private_chat"]
                description: |-
                  Convenience parameter for setting various default state events
                  based on a preset. Must be either:

                  ``private_chat`` =>
                    ``join_rules`` is set to ``invite``.
                    ``history_visibility`` is set to ``shared``.

                  ``trusted_private_chat`` =>
                      ``join_rules`` is set to ``invite``.
                      ``history_visibility`` is set to ``shared``.
                      All invitees are given the same power level as the room creator.

                  ``public_chat``: =>
                      ``join_rules`` is set to ``public``.
                      ``history_visibility`` is set to ``shared``.

      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 body is malformed or the room alias specified is already taken.
      tags:
        - Room creation