You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
297 lines
13 KiB
YAML
297 lines
13 KiB
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
|