# 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: 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, giving the room creator (and not other members) permission to send state events. Overridden by the `power_level_content_override` parameter. 4. Events set by the `preset`. Currently these are the `m.room.join_rules`, `m.room.history_visibility`, and `m.room.guest_access` state events. 5. Events listed in `initial_state`, in the order that they are listed. 6. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` state events). 7. 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`. operationId: createRoom security: - accessToken: [] parameters: - in: body name: body description: The desired room configuration. required: true 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`. The complete room alias will become the canonical alias for the room. 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. id_access_token: type: string description: |- 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. 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", "id_access_token", "medium", "address"] 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 description: |- Extra keys, such as `m.federate`, to be added to the content of the `m.room.create`_ event. The server will clobber the following keys: `creator`, `room_version`. 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. If unspecified, the server should use the `visibility` to determine which preset to use. A visbility 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`_ 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`_ event content prior to it being sent to the room. Defaults to overriding nothing. 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. required: ['room_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`). - 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. schema: "$ref": "definitions/errors/error.yaml" tags: - Room creation