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.
matrix-spec/data/api/client-server/create_room.yaml

294 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, giving the room creator
Add general clarity to the /createRoom endpoint This commit does a number of things: * Minor formatting/alignment changes * Document the room_alias response key. This could be deprecated now, or forfeited, if needed. * Remove the guest_can_join parameter - it is not actually supported * Document the previously undocumented power_level_content_override parameter * Clarify that the room_id is required on the response * More clearly spell out which events are created as part of the request * Clarify how the room alias becomes the canonical alias * Clarify how the `visibility` may be used to determine a default preset to apply * Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value References: * Preset being inferred by the visibility: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/synapse/handlers/room.py#L172-L177 * Power level content overrides: * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198 * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359 * Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370 * `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315 Fixes https://github.com/matrix-org/matrix-doc/issues/1243 Fixes https://github.com/matrix-org/matrix-doc/issues/1471 Inspired by https://github.com/matrix-org/matrix-doc/issues/1213
6 years ago
(and not other members) permission to send state events. Overridden
by the `power_level_content_override` parameter.
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`
Add general clarity to the /createRoom endpoint This commit does a number of things: * Minor formatting/alignment changes * Document the room_alias response key. This could be deprecated now, or forfeited, if needed. * Remove the guest_can_join parameter - it is not actually supported * Document the previously undocumented power_level_content_override parameter * Clarify that the room_id is required on the response * More clearly spell out which events are created as part of the request * Clarify how the room alias becomes the canonical alias * Clarify how the `visibility` may be used to determine a default preset to apply * Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value References: * Preset being inferred by the visibility: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/synapse/handlers/room.py#L172-L177 * Power level content overrides: * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198 * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359 * Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370 * `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315 Fixes https://github.com/matrix-org/matrix-doc/issues/1243 Fixes https://github.com/matrix-org/matrix-doc/issues/1471 Inspired by https://github.com/matrix-org/matrix-doc/issues/1213
6 years ago
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`.
operationId: createRoom
security:
- accessToken: []
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": {
Add general clarity to the /createRoom endpoint This commit does a number of things: * Minor formatting/alignment changes * Document the room_alias response key. This could be deprecated now, or forfeited, if needed. * Remove the guest_can_join parameter - it is not actually supported * Document the previously undocumented power_level_content_override parameter * Clarify that the room_id is required on the response * More clearly spell out which events are created as part of the request * Clarify how the room alias becomes the canonical alias * Clarify how the `visibility` may be used to determine a default preset to apply * Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value References: * Preset being inferred by the visibility: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/synapse/handlers/room.py#L172-L177 * Power level content overrides: * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198 * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359 * Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370 * `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315 Fixes https://github.com/matrix-org/matrix-doc/issues/1243 Fixes https://github.com/matrix-org/matrix-doc/issues/1471 Inspired by https://github.com/matrix-org/matrix-doc/issues/1213
6 years ago
"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`.
Add general clarity to the /createRoom endpoint This commit does a number of things: * Minor formatting/alignment changes * Document the room_alias response key. This could be deprecated now, or forfeited, if needed. * Remove the guest_can_join parameter - it is not actually supported * Document the previously undocumented power_level_content_override parameter * Clarify that the room_id is required on the response * More clearly spell out which events are created as part of the request * Clarify how the room alias becomes the canonical alias * Clarify how the `visibility` may be used to determine a default preset to apply * Document the `m.federate` creation content parameter, adding an option for the homeserver to define a default value References: * Preset being inferred by the visibility: https://github.com/matrix-org/synapse/blob/cd32c19a604549b4518d748c07149d140bc9e063/synapse/handlers/room.py#L172-L177 * Power level content overrides: * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L198 * https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L335-L359 * Aliases becoming canonical: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L366-L370 * `m.federate` landing in the create event: https://github.com/matrix-org/synapse/blob/master/synapse/handlers/room.py#L311-L315 Fixes https://github.com/matrix-org/matrix-doc/issues/1243 Fixes https://github.com/matrix-org/matrix-doc/issues/1471 Inspired by https://github.com/matrix-org/matrix-doc/issues/1213
6 years ago
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` 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
description: |-
The kind of address being passed in the address field, for example `email`
(see [the list of recognised values](/appendices/#3pid-types)).
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`](/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.
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 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](/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:
$ref: definitions/security.yaml