wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'master' into babolivier/standardised-federation-response-format

Browse source
This commit is contained in:
Brendan Abolivier 2019-09-05 14:54:48 +01:00
commit 48e8c55138
220 changed files with 7268 additions and 1498 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.buildkite/pipeline.yaml
View file

@ -9,3 +9,8 @@ steps:
plugins:
- docker#v3.0.1:
image: "python:3.6"
- label: "rebuild matrix.org"
trigger: "matrix-dot-org"
async: true
branches: "master"

2
.circleci/config.yml
View file

@ -97,7 +97,7 @@ jobs:
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/api/client-server/index.html"; echo $DOCS_URL
build-dev-scripts:
docker:
- image: golang:1.8
- image: golang:1.10
steps:
- checkout
- run:

34
CONTRIBUTING.rst
View file

@ -26,10 +26,11 @@ For this to be effective, the APIs need to be present and working correctly in a
server before they can be documented in the specification. This process can take
some time to complete.
For this reason, we have not found the github pull-request model effective for
discussing changes to the specification. Instead, we have adopted the workflow
as described at https://matrix.org/docs/spec/proposals - *please read this for
details on how to contribute spec changes*.
Changes to the protocol (new endpoints, ideas, etc) need to go through the
`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
If you're not sure, visit us at `#matrix-spec:matrix.org`_
and ask.
Other changes
@ -51,8 +52,7 @@ following:
<https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
(If there is any doubt about whether it is the spec or the implementations
that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_.)
that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
* Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility
@ -60,23 +60,23 @@ following:
`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
label.
For example, recommendations for UI behaviour do not require a proposal
document. On the other hand, changes to event contents would be best
discussed in a proposal document even though no changes would be necessary to
server implementations.
For example, areas where the specification is unclear do not require a proposal
to fix. On the other hand, introducing new behaviour is best represented by a
proposal.
For such changes, please do just open a `pull request`_.
For such changes, please do just open a `pull request`_. If you're not sure if
your change is covered by the above, please visit `#matrix-spec:matrix.org` and
ask.
.. _pull request: https://help.github.com/articles/about-pull-requests
.. _`pull request`: https://help.github.com/articles/about-pull-requests
.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
Adding to the changelog
~~~~~~~~~~~~~~~~~~~~~~~
Currently only changes to the client-server API need to end up in a changelog. The
other APIs are not yet stable and therefore do not have a changelog. Adding to the
changelog can only be done after you've opened your pull request, so be sure to do
that first.
All API specifications require a changelog entry. Adding to the changelog can only
be done after you've opened your pull request, so be sure to do that first.
The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
form of "news fragments". The news fragments for the client-server API are stored
@ -96,7 +96,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
* ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something
* ``deprecation`` - Used when deprecating something.
All news fragments must have a brief summary explaining the change in the
contents of the file. The summary must end in a full stop to be in line with

2
README.rst
View file

@ -138,4 +138,4 @@ Issue tracking
Issues with the Matrix specification are tracked in `GitHub
<https://github.com/matrix-org/matrix-doc/issues>`_.
See `meta/labels.rst <meta/labels.rst>`_ for notes on what the labels mean.
See `meta/github-labels.rst <meta/github-labels.rst>`_ for notes on what the labels mean.

2
api/application-service/transactions.yaml
View file

@ -56,7 +56,7 @@ paths:
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
{"$ref": "../../event-schemas/examples/m.room.message$m.text"}
]
}
description: Transaction information

112
api/client-server/administrative_contact.yaml
View file

@ -134,9 +134,27 @@ paths:
200:
description: The addition was successful.
examples:
application/json: {}
application/json: {
"submit_url": "https://example.org/path/to/submitToken"
}
schema:
type: object
properties:
submit_url:
type: string
description: |-
An optional field containing a URL where the client must
submit the validation token to, with identical parameters
to the Identity Service API's ``POST
/validate/email/submitToken`` endpoint. The homeserver must
send this token to the user (if applicable), who should
then be prompted to provide it to the client.
If this field is not present, the client can assume that
verification will happen without the client's involvement
provided the homeserver advertises this specification version
in the ``/versions`` response (ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
403:
description: The credentials could not be verified with the identity server.
examples:
@ -163,6 +181,14 @@ paths:
schema:
type: object
properties:
id_server:
type: string
description: |-
The identity server to unbind from. If not provided, the homeserver
MUST use the ``id_server`` the identifier was added through. If the
homeserver does not know the original ``id_server``, it MUST return
a ``id_server_unbind_result`` of ``no-support``.
example: "example.org"
medium:
type: string
description: The medium of the third party identifier being removed.
@ -180,41 +206,55 @@ paths:
user.
schema:
type: object
properties: {}
properties:
id_server_unbind_result:
type: string
enum:
# XXX: I don't know why, but the order matters here so that "no-support"
# doesn't become "no- support" by the renderer.
- "no-support"
- "success"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the 3PID from the identity server. ``success`` indicates that the
indentity server has unbound the identifier whereas ``no-support``
indicates that the identity server refuses to support the request
or the homeserver was not able to determine an identity server to
unbind from.
example: "success"
required:
- id_server_unbind_result
tags:
- User data
"/account/3pid/email/requestToken":
post:
summary: Begins the validation process for an email address for association with the user's account.
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address is **not** already associated
with an account on this homeserver. This API should be used to request
validation tokens when adding an email address to an account. This API's
parameters and response are identical to that of the |/register/email/requestToken|_
endpoint.
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding an email address to an
account. This API's parameters and response are identical to that of
the |/register/email/requestToken|_ endpoint. The homeserver has the
choice of validating the email address itself, or proxying the request
to the ``/validate/email/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
operationId: requestTokenTo3PIDEmail
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
description: |-
An email was sent to the given address. Note that this may be an
email containing the validation token or it may be informing the
user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -241,34 +281,28 @@ paths:
post:
summary: Begins the validation process for a phone number for association with the user's account.
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is **not** already associated
with an account on this homeserver. This API should be used to request
validation tokens when adding a phone number to an account. This API's
parameters and response are identical to that of the |/register/msisdn/requestToken|_
endpoint.
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. This API should
be used to request validation tokens when adding a phone number to an
account. This API's parameters and response are identical to that of
the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
choice of validating the phone number itself, or proxying the request
to the ``/validate/msisdn/requestToken`` Identity Service API as
identified by ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
operationId: requestTokenTo3PIDMSISDN
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a

139
api/client-server/content-repo.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -41,7 +42,7 @@ paths:
name: Content-Type
type: string
description: The content type of the file being uploaded
x-example: "Content-Type: audio/mpeg"
x-example: "Content-Type: application/pdf"
- in: query
type: string
x-example: "War and Peace.pdf"
@ -51,24 +52,48 @@ paths:
name: "<content>"
description: The content to be uploaded.
required: true
x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
schema:
type: string
example: "<bytes>"
format: byte
responses:
200:
description: The MXC URI for the uploaded content.
description: The `MXC URI`_ for the uploaded content.
schema:
type: object
required: ["content_uri"]
properties:
content_uri:
type: string
description: "The MXC URI to the uploaded content."
description: "The `MXC URI`_ to the uploaded content."
examples:
application/json: {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
403:
description: |-
The user does not have permission to upload the content. Some reasons for this error include:
- The server does not permit the file type.
- The user has reached a quota for uploaded content.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Cannot upload this content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The uploaded content is too large for the server.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Cannot upload files larger than 100mb"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -103,7 +128,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -113,10 +138,23 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of the file that was previously uploaded, if set."
description: |-
The name of the file that was previously uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -125,7 +163,9 @@ paths:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: "Download content from the content repository as a given filename."
summary: |-
Download content from the content repository. This is the same as
the download endpoint above, except permitting a desired file name.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
@ -148,8 +188,7 @@ paths:
name: fileName
x-example: filename.jpg
required: true
description: |
The filename to give in the Content-Disposition
description: A filename to give in the ``Content-Disposition`` header.
- in: query
type: boolean
name: allow_remote
@ -158,7 +197,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -168,10 +207,24 @@ paths:
description: "The content type of the file that was previously uploaded."
type: "string"
Content-Disposition:
description: "The name of file given in the request"
description: |-
The ``fileName`` requested or the name of the file that was previously
uploaded, if set.
type: "string"
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the uploaded file."
502:
description: |-
The content is too large for the server to serve.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to serve"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -180,7 +233,9 @@ paths:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
summary: |-
Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
section for more information.
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
@ -188,7 +243,7 @@ paths:
type: string
name: serverName
required: true
x-example: matrix.org
x-example: example.org
description: |
The server name from the ``mxc://`` URI (the authoritory component)
- in: path
@ -202,22 +257,26 @@ paths:
type: integer
x-example: 64
name: width
required: true
description: |-
The *desired* width of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* width of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: integer
x-example: 64
name: height
required: true
description: |-
The *desired* height of the thumbnail. The actual thumbnail may not
match the size specified.
The *desired* height of the thumbnail. The actual thumbnail may be
larger than the size specified.
- in: query
type: string
enum: ["crop", "scale"]
name: method
x-example: "scale"
description: The desired resizing method.
description: |-
The desired resizing method. See the `thumbnailing <#thumbnails>`_
section for more information.
- in: query
type: boolean
name: allow_remote
@ -226,7 +285,7 @@ paths:
default: true
description: |
Indicates to the server that it should not attempt to fetch the media if it is deemed
remote. This is to prevent routing loops where the server contacts itself. Defaults to
remote. This is to prevent routing loops where the server contacts itself. Defaults to
true if not provided.
responses:
200:
@ -238,6 +297,40 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
# This is a workaround for us not being able to say the response is required.
description: "**Required.** The bytes for the thumbnail."
400:
description: |-
The request does not make sense to the server, or the server cannot thumbnail
the content. For example, the client requested non-integer dimensions or asked
for negatively-sized images.
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "Cannot generate thumbnails for the requested content"
}
schema:
"$ref": "definitions/errors/error.yaml"
413:
description: |-
The local content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
502:
description: |-
The remote content is too large for the server to thumbnail.
examples:
application/json: {
"errcode": "M_TOO_LARGE",
"error": "Content is too large to thumbnail"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -256,7 +349,7 @@ paths:
type: string
x-example: "https://matrix.org"
name: url
description: "The URL to get a preview of"
description: "The URL to get a preview of."
required: true
- in: query
type: integer
@ -284,7 +377,7 @@ paths:
"og:image":
type: string
description: |-
An MXC URI to the image. Omitted if there is no image.
An `MXC URI`_ to the image. Omitted if there is no image.
examples:
application/json: {
"og:title": "Matrix Blog Post",
@ -328,7 +421,7 @@ paths:
m.upload.size:
type: integer
format: int64
description: |-
description: |-
The maximum size an upload can be in bytes.
Clients SHOULD use this as a guide when uploading content.
If not listed or null, the size limit should be treated as unknown.

2
api/client-server/definitions/device_keys.yaml
View file

@ -33,7 +33,7 @@ properties:
type: string
description: |-
The encryption algorithms supported by this device.
example: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"]
example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"]
keys:
type: object
description: |-

12
api/client-server/definitions/push_condition.yaml
View file

@ -16,16 +16,20 @@ title: PushCondition
type: object
properties:
kind:
enum:
- event_match
- contains_display_name
- room_member_count
type: string
description: |-
The kind of condition to apply. See `conditions <#conditions>`_ for
more information on the allowed kinds and how they work.
key:
type: string
description: |-
Required for ``event_match`` conditions. The dot-separated field of the
event to match.
Required for ``sender_notification_permission`` conditions. The field in
the power level event the user needs a minimum power level for. Fields
must be specified under the ``notifications`` property in the power level
event's ``content``.
x-example: content.body
pattern:
type: string

26
api/client-server/definitions/request_email_validation.yaml Normal file
View file

@ -0,0 +1,26 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
allOf:
- $ref: "../../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May optionally
include a port. This parameter is ignored when the homeserver handles
3PID verification.
example: "id.example.com"
required: ["id_server"]

26
api/client-server/definitions/request_msisdn_validation.yaml Normal file
View file

@ -0,0 +1,26 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
allOf:
- $ref: "../../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May optionally
include a port. This parameter is ignored when the homeserver handles
3PID verification.
example: "id.example.com"
required: ["id_server"]

37
api/client-server/definitions/request_token_response.yaml Normal file
View file

@ -0,0 +1,37 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
properties:
sid:
type: string
description: |-
The session ID. Session IDs are opaque strings that must consist entirely
of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255
characters and they must not be empty.
example: "123abc"
submit_url:
type: string
description: |-
An optional field containing a URL where the client must submit the
validation token to, with identical parameters to the Identity Service
API's ``POST /validate/email/submitToken`` endpoint. The homeserver must
send this token to the user (if applicable), who should then be
prompted to provide it to the client.
If this field is not present, the client can assume that verification
will happen without the client's involvement provided the homeserver
advertises this specification version in the ``/versions`` response
(ie: r0.5.0).
example: "https://example.org/path/to/submitToken"
required: ['sid']

14
api/client-server/definitions/room_event_filter.yaml
View file

@ -16,6 +16,20 @@ allOf:
- type: object
title: RoomEventFilter
properties:
lazy_load_members:
type: boolean
description: |-
If ``true``, enables lazy-loading of membership events. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
include_redundant_members:
type: boolean
description: |-
If ``true``, sends all membership events for all events, even if they have already
been sent to the client. Does not
apply unless ``lazy_load_members`` is ``true``. See
`Lazy-loading room members <#lazy-loading-room-members>`_
for more information. Defaults to ``false``.
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``

33
api/client-server/definitions/sync_filter.yaml
View file

@ -16,7 +16,7 @@ title: Filter
properties:
event_fields:
description: List of event fields to include. If this list is absent then all
fields are included. The entries may include '.' charaters to indicate sub-fields.
fields are included. The entries may include '.' characters to indicate sub-fields.
So ['content.body'] will include the 'body' field of the 'content' object. A
literal '.' character in a field name may be escaped using a '\\'. A server may
include more fields than were requested.
@ -25,7 +25,7 @@ properties:
type: array
event_format:
description: The format to use for events. 'client' will return the events in
a format suitable for clients. 'federation' will return the raw event as receieved
a format suitable for clients. 'federation' will return the raw event as received
over federation. The default is 'client'.
enum:
- client
@ -47,7 +47,7 @@ properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
filter. This filter is applied before the filters in ``ephemeral``,
filter. This filter is applied before the filters in ``ephemeral``,
``state``, ``timeline`` or ``account_data``
items:
type: string
@ -73,33 +73,6 @@ properties:
allOf:
- $ref: room_event_filter.yaml
description: The state events to include for rooms.
properties:
lazy_load_members:
type: boolean
description: |-
If ``true``, the only ``m.room.member`` events returned in
the ``state`` section of the ``/sync`` response are those
which are definitely necessary for a client to display
the ``sender`` of the timeline events in that response.
If ``false``, ``m.room.member`` events are not filtered.
By default, servers should suppress duplicate redundant
lazy-loaded ``m.room.member`` events from being sent to a given
client across multiple calls to ``/sync``, given that most clients
cache membership events (see ``include_redundant_members``
to change this behaviour).
include_redundant_members:
type: boolean
description: |-
If ``true``, the ``state`` section of the ``/sync`` response will
always contain the ``m.room.member`` events required to display
the ``sender`` of the timeline events in that response, assuming
``lazy_load_members`` is enabled. This means that redundant
duplicate member events may be returned across multiple calls to
``/sync``. This is useful for naive clients who never track
membership data. If ``false``, duplicate ``m.room.member`` events
may be suppressed by the server across multiple calls to ``/sync``.
If ``lazy_load_members`` is ``false`` this field is ignored.
timeline:
allOf:
- $ref: room_event_filter.yaml

41
api/client-server/definitions/third_party_signed.yaml Normal file
View file

@ -0,0 +1,41 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
title: Third Party Signed
description: |-
A signature of an ``m.third_party_invite`` token to prove that this user
owns a third party identity which has been invited to the room.
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
example: "@alice:example.org"
mxid:
type: string
description: The Matrix ID of the invitee.
example: "@bob:example.org"
token:
type: string
description: The state key of the m.third_party_invite event.
example: "random8nonce"
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
example: {
"example.org": {
"ed25519:0": "some9signature"
}
}
required: ["sender", "mxid", "token", "signatures"]

9
api/client-server/directory.yaml
View file

@ -148,5 +148,14 @@ paths:
}
schema:
type: object
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:example.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory

91
api/client-server/event_context.yaml
View file

@ -34,6 +34,9 @@ paths:
This API returns a number of events that happened just before and
after the specified event. This allows clients to get the context
surrounding an event.
*Note*: This endpoint supports lazy-loading of room member events. See
`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
operationId: getEventContext
security:
- accessToken: []
@ -101,65 +104,35 @@ paths:
- "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: {
"end": "t29-57_2_0_2",
"events_after": [
{
"age": 91911336,
"content": {
"body": "7",
"msgtype": "m.text"
},
"event_id": "$14460306086CiUaL:localhost:8480",
"origin_server_ts": 1446030608551,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
}
],
"events_before": [
{
"age": 91911903,
"content": {
"body": "5",
"msgtype": "m.text"
},
"event_id": "$14460306074UYTlh:localhost:8480",
"origin_server_ts": 1446030607984,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"type": "m.room.message",
"sender": "@test:localhost:8480"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"age": 3123715284,
"content": {
"creator": "@test:localhost:8480"
},
"event_id": "$14429988040dgQAE:localhost:8480",
"origin_server_ts": 1442998804603,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "",
"type": "m.room.create",
"sender": "@test:localhost:8480"
},
{
"age": 2067105053,
"content": {
"avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
"displayname": "Bob2",
"membership": "join"
},
"event_id": "$14440554144URDbf:localhost:8480",
"origin_server_ts": 1444055414834,
"replaces_state": "$14440552472PgiGk:localhost:8480",
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"state_key": "@test:localhost:8480",
"type": "m.room.member",
"sender": "@test:localhost:8480"
}
]
"end": "t29-57_2_0_2",
"events_after": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"event": {
"event_id": "$f3h4d129462ha:example.com",
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.image"
},
"events_before": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}
tags:
- Room participation

69
api/client-server/joining.yaml
View file

@ -58,38 +58,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-
@ -163,45 +134,9 @@ paths:
name: third_party_signed
schema:
type: object
example: {
"third_party_signed": {
"signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
"token": "random8nonce",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
}
}
}
}
properties:
third_party_signed:
type: object
title: ThirdPartySigned
description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
properties:
signed:
type: object
title: Signed
properties:
sender:
type: string
description: The Matrix ID of the user who issued the invite.
mxid:
type: string
description: The Matrix ID of the invitee.
token:
type: string
description: The state key of the m.third_party_invite event.
signatures:
type: object
description: A signatures object containing a signature of the entire signed object.
title: Signatures
required: ["sender", "mxid", "token", "signatures"]
required: ["signed"]
$ref: "definitions/third_party_signed.yaml"
responses:
200:
description: |-

106
api/client-server/keys.yaml
View file

@ -56,25 +56,48 @@ paths:
One-time public keys for "pre-key" messages. The names of
the properties should be in the format
``<algorithm>:<key_id>``. The format of the key is determined
by the key algorithm.
by the `key algorithm <#key-algorithms>`_.
May be absent if no new one-time keys are required.
additionalProperties:
type:
- string
- object
example:
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8"
signed_curve25519:AAAAHg:
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
signed_curve25519:AAAAHQ:
key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
# - type: object
# title: KeyObject
# properties:
# key:
# type: string
# description: The key, encoded using unpadded base64.
# signatures:
# type: object
# description: |-
# Signature for the device. Mapped from user ID to signature object.
# additionalProperties:
# type: string
# required: ['key', 'signatures']
example: {
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
},
"signed_curve25519:AAAAHQ": {
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
}
}
responses:
200:
description:
@ -194,8 +217,8 @@ paths:
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
"m.olm.v1.curve25519-aes-sha2",
"m.megolm.v1.aes-sha2"
],
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
@ -205,12 +228,12 @@ paths:
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
},
"unsigned": {
"device_display_name": "Alice's mobile phone"
}
}
tags:
- End-to-end encryption
"/keys/claim":
@ -246,14 +269,15 @@ paths:
type: string
description: algorithm
example: "signed_curve25519"
example:
example: {
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
}
required:
- one_time_keys
responses:
200:
description:
The claimed keys
The claimed keys.
schema:
type: object
properties:
@ -263,7 +287,7 @@ paths:
If any remote homeservers could not be reached, they are
recorded here. The names of the properties are the names of
the unreachable servers.
If the homeserver could be reached, but the user or device
was unknown, no failure is recorded. Instead, the corresponding
user or device is missing from the ``one_time_keys`` result.
@ -275,20 +299,46 @@ paths:
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the `key algorithms <#key-algorithms>`_ section for information
on the Key Object format.
additionalProperties:
type: object
additionalProperties:
type:
- string
- object
example:
"@alice:example.com":
JLAFKJWSCS:
signed_curve25519:AAAAHg:
key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
signatures:
"@alice:example.com":
ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
# XXX: We can't define an actual object here, so we have to hope
# that people will look at the swagger source or can figure it out
# from the other endpoints/example.
# - type: object
# title: KeyObject
# properties:
# key:
# type: string
# description: The key, encoded using unpadded base64.
# signatures:
# type: object
# description: |-
# Signature for the device. Mapped from user ID to signature object.
# additionalProperties:
# type: string
# required: ['key', 'signatures']
example: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
}
required: ['one_time_keys']
tags:
- End-to-end encryption
"/keys/changes":

7
api/client-server/login.yaml
View file

@ -194,10 +194,13 @@ paths:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The login attempt failed. For example, the password may have been incorrect.
The login attempt failed. This can include one of the following error codes:
* ``M_FORBIDDEN``: The provided authentication data was incorrect.
* ``M_USER_DEACTIVATED``: The user has been deactivated.
examples:
application/json: {
"errcode": "M_FORBIDDEN"}
"errcode": "M_FORBIDDEN"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:

7
api/client-server/logout.yaml
View file

@ -32,7 +32,8 @@ paths:
summary: Invalidates a user access token
description: |-
Invalidates an existing access token, so that it can no longer be used for
authorization.
authorization. The device associated with the access token is also deleted.
`Device keys <#device-keys>`_ for the device are deleted alongside the device.
operationId: logout
security:
- accessToken: []
@ -49,7 +50,9 @@ paths:
summary: Invalidates all access tokens for a user
description: |-
Invalidates all access tokens for a user, so that they can no longer be used for
authorization. This includes the access token that made this request.
authorization. This includes the access token that made this request. All devices
for the user are also deleted. `Device keys <#device-keys>`_ for the device are
deleted alongside the device.
This endpoint does not require UI authorization because UI authorization is
designed to protect against attacks where the someone gets hold of a single access

62
api/client-server/message_pagination.yaml
View file

@ -33,6 +33,9 @@ paths:
description: |-
This API returns a list of message and state events for a room. It uses
pagination query parameters to paginate history in the room.
*Note*: This endpoint supports lazy-loading of room member events. See
`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
operationId: getRoomEvents
security:
- accessToken: []
@ -103,54 +106,45 @@ paths:
chunk:
type: array
description: |-
A list of room events.
A list of room events. The order depends on the ``dir`` parameter.
For ``dir=b`` events will be in reverse-chronological order,
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
state:
type: array
description: |-
A list of state events relevant to showing the ``chunk``. For example, if
``lazy_load_members`` is enabled in the filter then this may contain
the membership events for the senders of events in the ``chunk``.
Unless ``include_redundant_members`` is ``true``, the server
may remove membership events which would have already been
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
type: object
title: RoomStateEvent
$ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [
{
"origin_server_ts": 1444812213737,
"sender": "@alice:example.com",
"event_id": "$1444812213350496Caaaa:example.com",
"content": {
"body": "hello world",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 1042
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"origin_server_ts": 1444812194656 ,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Cbbbb:example.com",
"content": {
"body": "the world is big",
"msgtype":"m.text"
},
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.message",
"age": 20123
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.name"
},
{
"origin_server_ts": 1444812163990,
"sender": "@bob:example.com",
"event_id": "$1444812213350496Ccccc:example.com",
"content": {
"name": "New room name"
},
"prev_content": {
"name": "Old room name"
},
"state_key": "",
"room_id":"!Xq3620DUiqCaoxq:example.com",
"type":"m.room.name",
"age": 50789
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
]
}

11
api/client-server/notifications.yaml
View file

@ -75,16 +75,7 @@ paths:
"room_id": "!abcdefg:example.com",
"ts": 1475508881945,
"event": {
"sender": "@alice:example.com",
"type": "m.room.message",
"age": 124524,
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

136
api/client-server/old_sync.yaml
View file

@ -64,18 +64,7 @@ paths:
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
}
{"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
]
}
schema:
@ -142,16 +131,7 @@ paths:
application/json: {
"end": "s3456_9_0",
"presence": [
{
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"last_active_ago": 31053,
"presence": "online",
"user_id": "@bob:localhost"
},
"type": "m.presence"
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
],
"account_data": [
{
@ -167,28 +147,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:localhost",
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
],
"end": "s3456_9_0",
@ -197,81 +161,20 @@ paths:
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:localhost",
"origin_server_ts": 1425999732392,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:localhost",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:localhost"
},
"event_id": "$14259997320KhbwJ:localhost",
"origin_server_ts": 1425999732089,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:localhost",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:localhost",
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member",
"sender": "@bob:localhost"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:localhost": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:localhost",
"origin_server_ts": 1425999732285,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:localhost"
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",
@ -423,16 +326,7 @@ paths:
200:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
application/json: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
schema:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"

12
api/client-server/peeking_events.yaml
View file

@ -75,16 +75,8 @@ paths:
"end": "s3457_9_0",
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"sender": "@bob:localhost"
"room_id": "!somewhere:over.the.rainbow",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
]
}

9
api/client-server/pushrules.yaml
View file

@ -159,8 +159,13 @@ paths:
],
"conditions": [
{
"is": "2",
"kind": "room_member_count"
"kind": "room_member_count",
"is": "2"
},
{
"kind": "event_match",
"key": "type",
"pattern": "m.room.message"
}
],
"default": true,

226
api/client-server/registration.yaml
View file

@ -29,7 +29,8 @@ paths:
post:
summary: Register for an account on this homeserver.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_, except in
the cases where a guest account is being registered.
Register for an account on this homeserver.
@ -59,6 +60,14 @@ paths:
supplied by the client or generated by the server. The server may
invalidate any access token previously associated with that device. See
`Relationship between access tokens and devices`_.
When registering a guest account, all parameters in the request body
with the exception of ``initial_device_display_name`` MUST BE ignored
by the server. The server MUST pick a ``device_id`` for the account
regardless of input.
Any user ID returned by this API must conform to the grammar given in the
`Matrix specification <../appendices.html#user-identifiers>`_.
operationId: register
parameters:
- in: query
@ -72,7 +81,7 @@ paths:
enum:
- guest
- user
description: The kind of account to register. Defaults to `user`.
description: The kind of account to register. Defaults to ``user``.
- in: body
name: body
schema:
@ -80,13 +89,11 @@ paths:
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself. It should be
left empty, or omitted, unless an earlier call returned an
response with status code 401.
Additional authentication information for the
user-interactive authentication API. Note that this
information is *not* used to define how the registered user
should be authenticated, but is instead used to
authenticate the ``register`` call itself.
"$ref": "definitions/auth_data.yaml"
bind_email:
type: boolean
@ -94,6 +101,12 @@ paths:
If true, the server binds the email used for authentication to
the Matrix ID with the identity server.
example: false
bind_msisdn:
type: boolean
description: |-
If true, the server binds the phone number used for authentication
to the Matrix ID with the identity server.
example: false
username:
type: string
description: |-
@ -142,7 +155,7 @@ paths:
The fully-qualified Matrix user ID (MXID) that has been registered.
Any user ID returned by this API must conform to the grammar given in the
`Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.
`Matrix specification <../appendices.html#user-identifiers>`_.
access_token:
type: string
description: |-
@ -194,6 +207,18 @@ paths:
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
403:
description: |-
The homeserver does not permit registering the account. This response
can be used to identify that a particular ``kind`` of account is not
allowed, or that registration is generally not supported by the homeserver.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Registration is disabled"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
@ -204,35 +229,28 @@ paths:
post:
summary: Begins the validation process for an email to be used during registration.
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address is not already associated
with an account on this homeserver. See the Identity Service API for
further information.
The homeserver must check that the given email address is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the email address itself, or proxying the
request to the ``/validate/email/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: |-
An email has been sent to the specified address.
Note that this may be an email containing the validation token or it may be informing
the user of an error.
An email has been sent to the specified address. Note that this
may be an email containing the validation token or it may be
informing the user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
@ -264,35 +282,28 @@ paths:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is not already associated
with an account on this homeserver. See the Identity Service API for
further information.
The homeserver must check that the given phone number is **not**
already associated with an account on this homeserver. The homeserver
has the choice of validating the phone number itself, or proxying the
request to the ``/validate/msisdn/requestToken`` Identity Service API. The
request should be proxied to the domain that is sent by the client in
the ``id_server``. It is imperative that the homeserver keep a list of
trusted Identity Servers and only proxies to those it trusts.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_msisdn_validation.yaml"
responses:
200:
description: |-
An SMS message has been sent to the specified phone number.
Note that this may be an SMS message containing the validation token or it may be informing
the user of an error.
An SMS message has been sent to the specified phone number. Note
that this may be an SMS message containing the validation token or
it may be informing the user of an error.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: The homeserver does not permit the address to be bound.
schema:
@ -326,13 +337,17 @@ paths:
description: |-
Changes the password for an account on this homeserver.
This API endpoint uses the `User-Interactive Authentication API`_.
This API endpoint uses the `User-Interactive Authentication API`_ to
ensure the user changing the password is actually the owner of the
account.
An access token should be submitted to this endpoint if the client has
an active session.
The homeserver may change the flows available depending on whether a
valid access token is provided.
valid access token is provided. The homeserver SHOULD NOT revoke the
access token provided in the request, however all other access tokens
for the user should be revoked if the request succeeds.
security:
- accessToken: []
operationId: changePassword
@ -373,16 +388,25 @@ paths:
post:
summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
description: |-
Proxies the Identity Service API ``validate/email/requestToken``, but
first checks that the given email address **is** associated with an account
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/email/requestToken|_ except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
The homeserver must check that the given email address **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
This API's parameters and response are identical to that of the
|/register/email/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
given email address could be found. The server may instead send an
email to the given address prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the email address itself,
or proxying the request to the ``/validate/email/requestToken``
Identity Service API. The request should be proxied to the domain that
is sent by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
@ -393,22 +417,12 @@ paths:
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_email_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "./definitions/request_email_validation.yaml"
responses:
200:
description: An email was sent to the given address.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -435,16 +449,24 @@ paths:
post:
summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
description: |-
Proxies the Identity Service API ``validate/msisdn/requestToken``, but
first checks that the given phone number **is** associated with an account
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/msisdn/requestToken|_ except that
`M_THREEPID_NOT_FOUND` may be returned if no account matching the
given phone number could be found. The server may instead send an
SMS message to the given address prompting the user to create an account.
`M_THREEPID_IN_USE` may not be returned.
The homeserver must check that the given phone number **is
associated** with an account on this homeserver. This API should be
used to request validation tokens when authenticating for the
``/account/password`` endpoint.
This API's parameters and response are identical to that of the
|/register/msisdn/requestToken|_ endpoint, except that
``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
given phone number could be found. The server may instead send the SMS
to the given phone number prompting the user to create an account.
``M_THREEPID_IN_USE`` may not be returned.
The homeserver has the choice of validating the phone number itself, or
proxying the request to the ``/validate/msisdn/requestToken`` Identity
Service API. The request should be proxied to the domain that is sent
by the client in the ``id_server``. It is imperative that the
homeserver keep a list of trusted Identity Servers and only proxies to
those that it trusts.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
@ -455,22 +477,12 @@ paths:
name: body
required: true
schema:
allOf:
- $ref: "../identity/definitions/request_msisdn_validation.yaml"
- type: object
properties:
id_server:
type: string
description: |-
The hostname of the identity server to communicate with. May
optionally include a port.
example: "id.example.com"
required: ['id_server']
$ref: "../identity/definitions/request_msisdn_validation.yaml"
responses:
200:
description: An SMS message was sent to the given phone number.
schema:
$ref: "../identity/definitions/sid.yaml"
$ref: "definitions/request_token_response.yaml"
403:
description: |-
The homeserver does not allow the third party identifier as a
@ -520,13 +532,39 @@ paths:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
id_server:
type: string
description: |-
The identity server to unbind all of the user's 3PIDs from.
If not provided, the homeserver MUST use the ``id_server``
that was originally use to bind each identifier. If the
homeserver does not know which ``id_server`` that was,
it must return an ``id_server_unbind_result`` of
``no-support``.
example: "example.org"
responses:
200:
description: The account has been deactivated.
examples:
application/json: {}
schema:
type: object
properties:
id_server_unbind_result:
type: string
enum:
- "success"
- "no-support"
description: |-
An indicator as to whether or not the homeserver was able to unbind
the user's 3PIDs from the identity server(s). ``success`` indicates
that all identifiers have been unbound from the identity server while
``no-support`` indicates that one or more identifiers failed to unbind
due to the identity server refusing the request or the homeserver
being unable to determine an identity server to unbind from. This
must be ``success`` if the homeserver has no identifiers to unbind
for the user.
example: "success"
required:
- id_server_unbind_result
401:
description: |-
The homeserver requires additional authentication information.

89
api/client-server/room_initial_sync.yaml
View file

@ -43,28 +43,12 @@ paths:
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:example.com",
"origin_server_ts": 1432804485886,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:example.com",
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"type": "m.room.message",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.message$m.file"
}
],
"end": "s3456_9_0",
@ -73,81 +57,20 @@ paths:
"room_id": "!636q39766251:example.com",
"state": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
],
"visibility": "private",

74
api/client-server/room_state.yaml
View file

@ -31,6 +31,9 @@ paths:
put:
summary: Send a state event to the given room.
description: |
.. For backwards compatibility with older links...
.. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
State events can be sent using this endpoint. These events will be
overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
match.
@ -61,7 +64,9 @@ paths:
- in: path
type: string
name: stateKey
description: The state_key for the state to send. Defaults to the empty string.
description: |-
The state_key for the state to send. Defaults to the empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: "@alice:example.com"
- in: body
@ -70,7 +75,7 @@ paths:
type: object
example: {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
responses:
@ -99,68 +104,3 @@ paths:
}
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
put:
summary: Send a state event to the given room.
description: |
State events can be sent using this endpoint. This endpoint is
equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
with an empty `stateKey`. Previous state events with matching
`<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
Requests to this endpoint **cannot use transaction IDs**
like other ``PUT`` paths because they cannot be differentiated from the
``state_key``. Furthermore, ``POST`` is unsupported on state paths.
The body of the request should be the content object of the event; the
fields in this object will vary depending on the type of event. See
`Room Events`_ for the ``m.`` event specification.
operationId: setRoomState
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to set the state in
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.name"
- in: body
name: body
schema:
type: object
example: {
"name": "New name for the room"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
schema:
type: object
properties:
event_id:
type: string
description: |-
A unique identifier for the event.
403:
description: |-
The sender doesn't have permission to send the event into the room.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
tags:
- Room participation

230
api/client-server/rooms.yaml
View file

@ -42,7 +42,7 @@ paths:
name: roomId
description: The ID of the room the event is in.
required: true
x-example: "!asfDuShaf7Gafaw:matrix.org"
x-example: "!636q39766251:matrix.org"
- in: path
type: string
name: eventId
@ -54,26 +54,30 @@ paths:
description: The full event.
examples:
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"type": "m.room.message"
}
"room_id": "!636q39766251:matrix.org",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
schema:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
404:
description: The event was not found or you do not have permission to read this event.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Event not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}/{stateKey}":
get:
summary: Get the state identified by the type and key.
description: |-
.. For backwards compatibility with older links...
.. _`get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
Looks up the contents of a state event in a room. If the user is
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
@ -97,7 +101,9 @@ paths:
- in: path
type: string
name: stateKey
description: The key of the state to look up.
description: |-
The key of the state to look up. Defaults to an empty string. When
an empty string, the trailing slash on this endpoint is optional.
required: true
x-example: ""
responses:
@ -116,48 +122,6 @@ paths:
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}":
get:
summary: Get the state identified by the type, with the empty state key.
description: |-
Looks up the contents of a state event in a room. If the user is
joined to the room then the state is taken from the current
state of the room. If the user has left the room then the state is
taken from the state of the room when they left.
This looks up the state event with the empty state key.
operationId: getRoomStateByType
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room to look up the state in.
required: true
x-example: "!636q39766251:example.com"
- in: path
type: string
name: eventType
description: The type of state to look up.
required: true
x-example: "m.room.name"
responses:
200:
description: The content of the state event.
examples:
application/json: {
"name": "Example room name"}
schema:
type: object
404:
description: The room has no state with the given type or key.
403:
description: >
You aren't a member of the room and weren't previously a
member of the room.
tags:
- Room participation
"/rooms/{roomId}/state":
get:
summary: Get all state events in the current state of a room.
@ -178,84 +142,23 @@ paths:
description: The current state of the room
examples:
application/json: [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.join_rules",
"sender": "@alice:example.com"
},
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.create",
"sender": "@alice:example.com"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
},
{
"age": 7148267004,
"content": {
"ban": 50,
"events": {
"m.room.name": 100,
"m.room.power_levels": 100
},
"events_default": 0,
"kick": 50,
"redact": 50,
"state_default": 50,
"users": {
"@alice:example.com": 100
},
"users_default": 0
},
"event_id": "$14259997322mqfaq:example.com",
"origin_server_ts": 1425999732285,
"room_id": "!636q39766251:example.com",
"state_key": "",
"type": "m.room.power_levels",
"sender": "@alice:example.com"
}
]
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.join_rules"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.create"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.power_levels"
}
]
schema:
type: array
title: RoomState
@ -288,6 +191,44 @@ paths:
description: The room to get the member events for.
required: true
x-example: "!636q39766251:example.com"
- in: query
name: at
type: string
description: |-
The point in time (pagination token) to return members for in the room.
This token can be obtained from a ``prev_batch`` token returned for
each room by the sync API. Defaults to the current state of the room,
as determined by the server.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
# XXX: As mentioned in MSC1227, replacing `[not_]membership` with a JSON
# filter might be a better alternative.
# See https://github.com/matrix-org/matrix-doc/issues/1337
- in: query
name: membership
type: string
enum:
- join
- invite
- leave
- ban
description: |-
The kind of membership to filter for. Defaults to no filtering if
unspecified. When specified alongside ``not_membership``, the two
parameters create an 'or' condition: either the membership *is*
the same as ``membership`` **or** *is not* the same as ``not_membership``.
x-example: "join"
- in: query
name: not_membership
type: string
enum:
- join
- invite
- leave
- ban
description: |-
The kind of membership to exclude from the results. Defaults to no
filtering if unspecified.
x-example: leave
security:
- accessToken: []
responses:
@ -300,33 +241,8 @@ paths:
application/json: {
"chunk": [
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member",
"sender": "@alice:example.com"
},
{
"age": 1622568720,
"content": {
"avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"membership": "join"
},
"event_id": "$1431525430134MxlLX:example.com",
"origin_server_ts": 1431525430569,
"replaces_state": "$142652023736BSXcM:example.com",
"room_id": "!636q39766251:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member",
"sender": "@bob:example.com"
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
}

13
api/client-server/search.yaml
View file

@ -280,7 +280,7 @@ paths:
Any groups that were requested.
The outer ``string`` key is the group key requested (eg: ``room_id``
or ``sender``). The inner ``string`` key is the grouped value (eg:
or ``sender``). The inner ``string`` key is the grouped value (eg:
a room's ID or a user's ID).
additionalProperties:
type: object
@ -347,16 +347,9 @@ paths:
{
"rank": 0.00424866,
"result": {
"age": 526228296,
"content": {
"body": "Test content martians and men",
"msgtype": "m.text"
},
"event_id": "$144429830826TWwbB:localhost",
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"type": "m.room.message",
"sender": "@test:localhost"
"event_id": "$144429830826TWwbB:localhost",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
}
]

143
api/client-server/sync.yaml
View file

@ -34,6 +34,20 @@ paths:
Clients use this API when they first log in to get an initial snapshot
of the state on the server, and then continue to call this API to get
incremental deltas to the state, and to receive new messages.
*Note*: This endpoint supports lazy-loading. See `Filtering <#filtering>`_
for more information. Lazy-loading members is only supported on a ``StateFilter``
for this endpoint. When lazy-loading is enabled, servers MUST include the
syncing user's own membership event when they join a room, or when the
full state of rooms is requested, to aid discovering the user's avatar &
displayname.
Like other members, the user's own membership event is eligible
for being considered redundant by the server. When a sync is ``limited``,
the server MUST return membership events for events in the gap
(between ``since`` and the start of the returned timeline), regardless
as to whether or not they are redundant. This ensures that joins/leaves
and profile changes which occur during the gap are not lost.
operationId: sync
security:
- accessToken: []
@ -49,6 +63,8 @@ paths:
requests. Creating a filter using the filter API is recommended for
clients that reuse the same filter multiple times, for example in
long poll requests.
See `Filtering <#filtering>`_ for more information.
x-example: "66696p746572"
- in: query
name: since
@ -125,6 +141,50 @@ paths:
title: Joined Room
type: object
properties:
summary:
title: RoomSummary
type: object
description: |-
Information about the room which clients may need to
correctly render it to users.
properties:
"m.heroes":
type: array
description: |-
The users which can be used to generate a room name
if the room does not have one. Required if the room's
``m.room.name`` or ``m.room.canonical_alias`` state events
are unset or empty.
This should be the first 5 members of the room, ordered
by stream ordering, which are joined or invited. The
list must never include the client's own user ID. When
no joined or invited members are available, this should
consist of the banned and left users. More than 5 members
may be provided, however less than 5 should only be provided
when there are less than 5 members to represent.
When lazy-loading room members is enabled, the membership
events for the heroes MUST be included in the ``state``,
unless they are redundant. When the list of users changes,
the server notifies the client by sending a fresh list of
heroes. If there are no changes since the last sync, this
field may be omitted.
items:
type: string
"m.joined_member_count":
type: integer
description: |-
The number of users with ``membership`` of ``join``,
including the client's own user ID. If this field has
not changed since the last sync, it may be omitted.
Required otherwise.
"m.invited_member_count":
type: integer
description: |-
The number of users with ``membership`` of ``invite``.
If this field has not changed since the last sync, it
may be omitted. Required otherwise.
state:
title: State
type: object
@ -167,11 +227,13 @@ paths:
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
"unread_notifications":
unread_notifications:
title: Unread Notification Counts
type: object
description: |-
Counts of unread notifications for this room
Counts of unread notifications for this room. See the
`Receiving notifications section <#receiving-notifications>`_
for more information on how these are calculated.
properties:
highlight_count:
title: Highlighted notification count
@ -212,30 +274,7 @@ paths:
events:
description: The StrippedState events that form the invite state.
items:
description: |-
A stripped down state event, with only the ``type``, ``state_key``,
``sender``, and ``content`` keys.
properties:
content:
description: The ``content`` for the event.
title: EventContent
type: object
state_key:
description: The ``state_key`` for the event.
type: string
type:
description: The ``type`` for the event.
type: string
sender:
description: The ``sender`` for the event.
type: string
required:
- type
- state_key
- content
- sender
title: StrippedState
type: object
$ref: "definitions/event-schemas/schema/stripped_state.yaml"
type: array
leave:
title: Left rooms
@ -310,11 +349,7 @@ paths:
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.presence",
"content": {"presence": "online"}
}
{"$ref": "definitions/event-schemas/examples/m.presence"}
]
},
"account_data": {
@ -330,39 +365,31 @@ paths:
"rooms": {
"join": {
"!726s6s6q:example.com": {
"summary": {
"m.heroes": [
"@alice:example.com",
"@bob:example.com"
],
"m.joined_member_count": 2,
"m.invited_member_count": 0
},
"state": {
"events": [
{
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@alice:example.com",
"content": {"membership": "join"},
"origin_server_ts": 1417731086795,
"event_id": "$66697273743031:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
}
]
},
"timeline": {
"events": [
{
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "join"},
"prev_content": {"membership": "invite"},
"origin_server_ts": 1417731086795,
"event_id": "$7365636s6r6432:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.member"
},
{
"sender": "@alice:example.com",
"type": "m.room.message",
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
"room_id": "!726s6s6q:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
}
],
"limited": true,
@ -370,18 +397,12 @@ paths:
},
"ephemeral": {
"events": [
{
"type": "m.typing",
"content": {"user_ids": ["@alice:example.com"]}
}
{"$ref": "definitions/event-schemas/examples/m.typing"}
]
},
"account_data": {
"events": [
{
"type": "m.tag",
"content": {"tags": {"work": {"order": 1}}}
},
{"$ref": "definitions/event-schemas/examples/m.tag"},
{
"type": "org.example.custom.room.config",
"content": {

99
api/identity/associations.yaml
View file

@ -30,6 +30,7 @@ paths:
description: |-
Determines if a given 3pid has been validated by a user.
operationId: getValidated3pid
deprecated: true
parameters:
- in: query
type: string
@ -104,6 +105,7 @@ paths:
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: bind
deprecated: true
parameters:
- in: body
name: body
@ -201,3 +203,100 @@ paths:
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/unbind":
post:
summary: Remove an association between a session and a Matrix user ID.
description: |-
Remove an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session's 3pids will not
return the removed association.
The identity server should authenticate the request in one of two
ways:
1. The request is signed by the homeserver which controls the ``user_id``.
2. The request includes the ``sid`` and ``client_secret`` parameters,
as per ``/3pid/bind``, which proves ownership of the 3PID.
If this endpoint returns a JSON Matrix error, that error should be passed
through to the client requesting an unbind through a homeserver, if the
homeserver is acting on behalf of a client.
operationId: unbind
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
}
}
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using ``sid`` and ``client_secret`` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the `3PID Types`_ Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
responses:
200:
description: The association was successfully removed.
examples:
application/json: {}
schema:
type: object
400:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
404:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
403:
description: |-
The credentials supplied to authenticate the request were invalid.
This may also be returned if the identity server does not support
the chosen authentication method (such as blocking homeservers from
unbinding identifiers).
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
501:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.

8
api/identity/definitions/request_email_validation.yaml
View file

@ -39,12 +39,14 @@ properties:
avoid repeatedly sending the same email in the case of request
retries between the POSTing user and the identity server.
The client should increment this value if they desire a new
email (e.g. a reminder) to be sent.
email (e.g. a reminder) to be sent. If they do not, the server
should respond with success but not resend the email.
example: 1
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
server will redirect the user to this URL.
Optional. When the validation is completed, the identity server will
redirect the user to this URL. This option is ignored when submitting
3PID validation information through a POST request.
example: "https://example.org/congratulations.html"
required: ["client_secret", "email", "send_attempt"]

5
api/identity/definitions/request_msisdn_validation.yaml
View file

@ -51,7 +51,8 @@ properties:
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
server will redirect the user to this URL.
Optional. When the validation is completed, the identity server will
redirect the user to this URL. This option is ignored when submitting
3PID validation information through a POST request.
example: "https://example.org/congratulations.html"
required: ["client_secret", "country", "phone_number", "send_attempt"]

18
api/identity/definitions/security.yaml Normal file
View file

@ -0,0 +1,18 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
accessToken:
type: apiKey
description: The access_token returned by a call to ``/register``.
name: access_token
in: query

3
api/identity/email_associations.yaml
View file

@ -46,6 +46,7 @@ paths:
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailRequestToken
deprecated: true
parameters:
- in: body
name: body
@ -92,6 +93,7 @@ paths:
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPost
deprecated: true
parameters:
- in: body
name: body
@ -142,6 +144,7 @@ paths:
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: emailSubmitTokenGet
deprecated: true
parameters:
- in: query
type: string

1
api/identity/invitation_signing.yaml
View file

@ -33,6 +33,7 @@ paths:
The identity server will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
operationId: blindlySignStuff
deprecated: true
parameters:
- in: body
name: body

2
api/identity/lookup.yaml
View file

@ -32,6 +32,7 @@ paths:
summary: Look up the Matrix user ID for a 3pid.
description: Look up the Matrix user ID for a 3pid.
operationId: lookupUser
deprecated: true
parameters:
- in: query
type: string
@ -101,6 +102,7 @@ paths:
summary: Lookup Matrix user IDs for a list of 3pids.
description: Lookup Matrix user IDs for a list of 3pids.
operationId: lookupUsers
deprecated: true
parameters:
- in: body
name: body

3
api/identity/phone_associations.yaml
View file

@ -46,6 +46,7 @@ paths:
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnRequestToken
deprecated: true
parameters:
- in: body
name: body
@ -94,6 +95,7 @@ paths:
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPost
deprecated: true
parameters:
- in: body
name: body
@ -144,6 +146,7 @@ paths:
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: msisdnSubmitTokenGet
deprecated: true
parameters:
- in: query
type: string

1
api/identity/ping.yaml
View file

@ -36,6 +36,7 @@ paths:
This is primarly used for auto-discovery and health check purposes
by entities acting as a client for the identity server.
operationId: ping
deprecated: true
responses:
200:
description: An identity server is ready to serve requests.

3
api/identity/pubkey.yaml
View file

@ -30,6 +30,7 @@ paths:
description: |-
Get the public key for the passed key ID.
operationId: getPubKey
deprecated: true
parameters:
- in: path
type: string
@ -72,6 +73,7 @@ paths:
Check whether a long-term public key is valid. The response should always
be the same, provided the key exists.
operationId: isPubKeyValid
deprecated: true
parameters:
- in: query
type: string
@ -101,6 +103,7 @@ paths:
description: |-
Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValid
deprecated: true
parameters:
- in: query
type: string

48
api/identity/store_invite.yaml
View file

@ -50,31 +50,67 @@ paths:
requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
Currently, invites may only be issued for 3pids of the ``email`` medium.
Optional fields in the request should be populated to the best of the
server's ability. Identity servers may use these variables when notifying
the ``address`` of the pending invite for display purposes.
operationId: storeInvite
deprecated: true
parameters:
- in: body
name: body
schema:
type: object
example: {
"medium": "email",
"address": "foo@bar.baz",
"room_id": "!something:example.tld",
"sender": "@bob:example.com"
}
properties:
medium:
type: string
description: The literal string ``email``.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the ``m.room.canonical_alias``
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the ``m.room.avatar`` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The ``join_rule`` for the room to which the user is invited. This should
be retrieved from the ``m.room.join_rules`` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the ``m.room.name`` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
required: ["medium", "address", "room_id", "sender"]
responses:
200:

308
api/identity/v2_associations.yaml Normal file
View file

@ -0,0 +1,308 @@
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Establishing Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: |-
Determines if a given 3pid has been validated by a user.
operationId: getValidated3pidV2
security:
- accessToken: []
parameters:
- in: query
type: string
name: sid
description: The Session ID generated by the ``requestToken`` call.
required: true
x-example: 1234
- in: query
type: string
name: client_secret
description: The client secret passed to the ``requestToken`` call.
required: true
x-example: monkeys_are_GREAT
responses:
200:
description: Validation information for the session.
examples:
application/json: {
"medium": "email",
"validated_at": 1457622739026,
"address": "louise@bobs.burgers"
}
schema:
type: object
properties:
medium:
type: string
description: The medium type of the 3pid.
address:
type: string
description: The address of the 3pid being looked up.
validated_at:
type: integer
description: |-
Timestamp, in milliseconds, indicating the time that the 3pid
was validated.
required: ['medium', 'address', 'validated_at']
400:
description: |-
The session has not been validated.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found.
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
Publish an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session\'s 3pids will return
this association.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: bindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:matrix.org"
}
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
mxid:
type: string
description: The Matrix user ID to associate with the 3pids.
required: ["sid", "client_secret", "mxid"]
responses:
200:
description: The association was published.
examples:
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
"not_before": 1428825849161,
"not_after": 4582425849161,
"ts": 1428825849161,
"signatures": {
"matrix.org": {
"ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ"
}
}
}
schema:
type: object
properties:
address:
type: string
description: The 3pid address of the user being looked up.
medium:
type: string
description: The medium type of the 3pid.
mxid:
type: string
description: The Matrix user ID associated with the 3pid.
not_before:
type: integer
description: A unix timestamp before which the association is not known to be valid.
not_after:
type: integer
description: A unix timestamp after which the association is not known to be valid.
ts:
type: integer
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: |-
The signatures of the verifying identity servers which show that the
association should be trusted, if you trust the verifying identity
services.
$ref: "../../schemas/server-signatures.yaml"
required:
- address
- medium
- mxid
- not_before
- not_after
- ts
- signatures
400:
description: |-
The association was not published.
If the session has not been validated, then ``errcode`` will be
``M_SESSION_NOT_VALIDATED``. If the session has timed out, then
``errcode`` will be ``M_SESSION_EXPIRED``.
examples:
application/json: {
"errcode": "M_SESSION_NOT_VALIDATED",
"error": "This validation session has not yet been completed"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
404:
description: The Session ID or client secret were not found
examples:
application/json: {
"errcode": "M_NO_VALID_SESSION",
"error": "No valid session was found matching that sid and client secret"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/3pid/unbind":
post:
summary: Remove an association between a session and a Matrix user ID.
description: |-
Remove an association between a session and a Matrix user ID.
Future calls to ``/lookup`` for any of the session's 3pids will not
return the removed association.
The identity server should authenticate the request in one of two
ways:
1. The request is signed by the homeserver which controls the ``user_id``.
2. The request includes the ``sid`` and ``client_secret`` parameters,
as per ``/3pid/bind``, which proves ownership of the 3PID.
If this endpoint returns a JSON Matrix error, that error should be passed
through to the client requesting an unbind through a homeserver, if the
homeserver is acting on behalf of a client.
operationId: unbindV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"mxid": "@ears:example.org",
"threepid": {
"medium": "email",
"address": "monkeys_have_ears@example.org"
}
}
properties:
sid:
type: string
description: The Session ID generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret passed to the ``requestToken`` call.
mxid:
type: string
description: The Matrix user ID to remove from the 3pids.
threepid:
type: object
title: 3PID
description: |-
The 3PID to remove. Must match the 3PID used to generate the session
if using ``sid`` and ``client_secret`` to authenticate this request.
properties:
medium:
type: string
description: |-
A medium from the `3PID Types`_ Appendix, matching the medium
of the identifier to unbind.
address:
type: string
description: The 3PID address to remove.
required: ['medium', 'address']
required: ["threepid", "mxid"]
responses:
200:
description: The association was successfully removed.
examples:
application/json: {}
schema:
type: object
400:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
404:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.
403:
description: |-
The credentials supplied to authenticate the request were invalid.
This may also be returned if the identity server does not support
the chosen authentication method (such as blocking homeservers from
unbinding identifiers).
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Invalid homeserver signature"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
501:
description: |-
If the response body is not a JSON Matrix error, the identity server
does not support unbinds. If a JSON Matrix error is in the response
body, the requesting party should respect the error.

183
api/identity/v2_email_associations.yaml Normal file
View file

@ -0,0 +1,183 @@
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Email Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/validate/email/requestToken":
post:
summary: Request a token for validating an email address.
description: |-
Create a session for validating an email address.
The identity server will send an email containing a token. If that
token is presented to the identity server in the future, it indicates
that that user was able to read the email for that email address, and
so we validate ownership of the email address.
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/email/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the email
address given is already registered on the server.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_email_validation.yaml"
responses:
200:
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are:
- ``M_INVALID_EMAIL``: The email address provided was invalid.
- ``M_EMAIL_SEND_ERROR``: The validation email could not be sent.
examples:
application/json: {
"errcode": "M_INVALID_EMAIL",
"error": "The email address is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/email/submitToken":
post:
summary: Validate ownership of an email address.
description: |-
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
normalisation. Whether to do so is an implementation detail for the
identity server. Clients must always pass on the token without
modification.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
token:
type: string
description: The token generated by the ``requestToken`` call and emailed to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of an email address.
description: |-
Validate ownership of an email address.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the email address is considered to
have been validated. This does not publish any information publicly, or
associate the email address with any Matrix user ID. Specifically,
calls to ``/lookup`` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: emailSubmitTokenGetV2
security:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
x-example: 1234
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the ``requestToken`` call.
x-example: monkeys_are_GREAT
- in: query
type: string
name: token
required: true
description: The token generated by the ``requestToken`` call and emailed to the user.
x-example: atoken
responses:
"200":
description: Email address is validated.
"3xx":
description: |-
Email address is validated, and the ``next_link`` parameter was
provided to the ``requestToken`` call. The user must be redirected
to the URL provided by the ``next_link`` parameter.
"4xx":
description:
Validation failed.

101
api/identity/v2_invitation_signing.yaml Normal file
View file

@ -0,0 +1,101 @@
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Ephemeral Invitation Signing API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/sign-ed25519":
post:
summary: Sign invitation details
description: |-
Sign invitation details.
The identity server will look up ``token`` which was stored in a call
to ``store-invite``, and fetch the sender of the invite.
operationId: blindlySignStuffV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"mxid": "@foo:bar.com",
"token": "sometoken",
"private_key": "base64encodedkey"
}
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
token:
type: string
description: The token from the call to ``store-invite``.
private_key:
type: string
description: The private key, encoded as `Unpadded base64`_.
required: ["mxid", "token", "private_key"]
responses:
200:
description: The signed JSON of the mxid, sender, and token.
schema:
type: object
properties:
mxid:
type: string
description: The Matrix user ID of the user accepting the invitation.
sender:
type: string
description: The Matrix user ID of the user who sent the invitation.
signatures:
type: object
description: The signature of the mxid, sender, and token.
$ref: "../../schemas/server-signatures.yaml"
token:
type: string
description: The token for the invitation.
required: ['mxid', 'sender', 'signatures', 'token']
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
404:
description: The token was not found.
examples:
application/json: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

185
api/identity/v2_phone_associations.yaml Normal file
View file

@ -0,0 +1,185 @@
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Phone Number Associations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/validate/msisdn/requestToken":
post:
summary: Request a token for validating a phone number.
description: |-
Create a session for validating a phone number.
The identity server will send an SMS message containing a token. If
that token is presented to the identity server in the future, it
indicates that that user was able to read the SMS for that phone
number, and so we validate ownership of the phone number.
Note that homeservers offer APIs that proxy this API, adding
additional behaviour on top, for example,
``/register/msisdn/requestToken`` is designed specifically for use when
registering an account and therefore will inform the user if the phone
number given is already registered on the server.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnRequestTokenV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
$ref: "definitions/request_msisdn_validation.yaml"
responses:
200:
description: Session created.
schema:
$ref: "definitions/sid.yaml"
400:
description: |
An error ocurred. Some possible errors are:
- ``M_INVALID_ADDRESS``: The phone number provided was invalid.
- ``M_SEND_ERROR``: The validation SMS could not be sent.
- ``M_DESTINATION_REJECTED``: The identity server cannot deliver an
SMS to the provided country or region.
examples:
application/json: {
"errcode": "M_INVALID_ADDRESS",
"error": "The phone number is not valid"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/validate/msisdn/submitToken":
post:
summary: Validate ownership of a phone number.
description: |-
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number is considered to
have been validated. This does not publish any information publicly, or
associate the phone number address with any Matrix user
ID. Specifically, calls to ``/lookup`` will not show a binding.
The identity server is free to match the token case-insensitively, or
carry out other mapping operations such as unicode
normalisation. Whether to do so is an implementation detail for the
identity server. Clients must always pass on the token without
modification.
Note: for backwards compatibility with previous drafts of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPostV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
example: {
"sid": "1234",
"client_secret": "monkeys_are_GREAT",
"token": "atoken"
}
properties:
sid:
type: string
description: The session ID, generated by the ``requestToken`` call.
client_secret:
type: string
description: The client secret that was supplied to the ``requestToken`` call.
token:
type: string
description: The token generated by the ``requestToken`` call and sent to the user.
required: ["sid", "client_secret", "token"]
responses:
200:
description:
The success of the validation.
examples:
application/json: {
"success": true
}
schema:
type: object
properties:
success:
type: boolean
description: Whether the validation was successful or not.
required: ['success']
get:
summary: Validate ownership of a phone number.
description: |-
Validate ownership of a phone number.
If the three parameters are consistent with a set generated by a
``requestToken`` call, ownership of the phone number address is
considered to have been validated. This does not publish any
information publicly, or associate the phone number with any Matrix
user ID. Specifically, calls to ``/lookup`` will not show a binding.
Note that, in contrast with the POST version, this endpoint will be
used by end-users, and so the response should be human-readable.
operationId: msisdnSubmitTokenGetV2
security:
- accessToken: []
parameters:
- in: query
type: string
name: sid
required: true
description: The session ID, generated by the ``requestToken`` call.
x-example: 1234
- in: query
type: string
name: client_secret
required: true
description: The client secret that was supplied to the ``requestToken`` call.
x-example: monkeys_are_GREAT
- in: query
type: string
name: token
required: true
description: The token generated by the ``requestToken`` call and sent to the user.
x-example: atoken
responses:
"200":
description: Phone number is validated.
"3xx":
description: |-
Phone number address is validated, and the ``next_link`` parameter
was provided to the ``requestToken`` call. The user must be
redirected to the URL provided by the ``next_link`` parameter.
"4xx":
description:
Validation failed.

46
api/identity/v2_ping.yaml Normal file
View file

@ -0,0 +1,46 @@
# Copyright 2018 Kamax Sàrl
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Ping API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
paths:
"/v2":
get:
summary: Checks that an identity server is available at this API endpoint.
description: |-
Checks that an identity server is available at this API endpoint.
To discover that an identity server is available at a specific URL,
this endpoint can be queried and will return an empty object.
This is primarly used for auto-discovery and health check purposes
by entities acting as a client for the identity server.
operationId: pingV2
responses:
200:
description: An identity server is ready to serve requests.
examples:
application/json: {}
schema:
type: object

127
api/identity/v2_pubkey.yaml Normal file
View file

@ -0,0 +1,127 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Public Key API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
paths:
"/pubkey/{keyId}":
get:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
operationId: getPubKeyV2
parameters:
- in: path
type: string
name: keyId
required: true
description: |-
The ID of the key. This should take the form algorithm:identifier
where algorithm identifies the signing algorithm, and the identifier
is an opaque string.
x-example: "ed25519:0"
responses:
200:
description:
The public key exists.
examples:
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
schema:
type: object
properties:
public_key:
type: string
description: Unpadded Base64 encoded public key.
required: ['public_key']
404:
description:
The public key was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "The public key was not found"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/pubkey/isvalid":
get:
summary: Check whether a long-term public key is valid.
description: |-
Check whether a long-term public key is valid. The response should always
be the same, provided the key exists.
operationId: isPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']
"/pubkey/ephemeral/isvalid":
get:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValidV2
parameters:
- in: query
type: string
name: public_key
required: true
description: |-
The unpadded base64-encoded public key to check.
x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
responses:
200:
description:
The validity of the public key.
examples:
application/json: {
"valid": true
}
schema:
type: object
properties:
valid:
type: boolean
description: Whether the public key is recognised and is currently valid.
required: ['valid']

165
api/identity/v2_store_invite.yaml Normal file
View file

@ -0,0 +1,165 @@
# Copyright 2018 New Vector Ltd
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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 Identity Service Store Invitations API"
version: "2.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/store-invite":
post:
summary: Store pending invitations to a user's 3pid.
description: |-
Store pending invitations to a user's 3pid.
In addition to the request parameters specified below, an arbitrary
number of other parameters may also be specified. These may be used in
the invite message generation described below.
The service will generate a random token and an ephemeral key used for
accepting the invite.
The service also generates a ``display_name`` for the inviter, which is
a redacted version of ``address`` which does not leak the full contents
of the ``address``.
The service records persistently all of the above information.
It also generates an email containing all of this data, sent to the
``address`` parameter, notifying them of the invitation.
Also, the generated ephemeral public key will be listed as valid on
requests to ``/_matrix/identity/v2/pubkey/ephemeral/isvalid``.
Currently, invites may only be issued for 3pids of the ``email`` medium.
Optional fields in the request should be populated to the best of the
server's ability. Identity servers may use these variables when notifying
the ``address`` of the pending invite for display purposes.
operationId: storeInviteV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
medium:
type: string
description: The literal string ``email``.
example: "email"
address:
type: string
description: The email address of the invited user.
example: "foo@example.com"
room_id:
type: string
description: The Matrix room ID to which the user is invited
example: "!something:example.org"
sender:
type: string
description: The Matrix user ID of the inviting user
example: "@bob:example.com"
room_alias:
type: string
description: |-
The Matrix room alias for the room to which the user is
invited. This should be retrieved from the ``m.room.canonical_alias``
state event.
example: "#somewhere:exmaple.org"
room_avatar_url:
type: string
description: |-
The Content URI for the room to which the user is invited. This should
be retrieved from the ``m.room.avatar`` state event.
example: "mxc://example.org/s0meM3dia"
room_join_rules:
type: string
description: |-
The ``join_rule`` for the room to which the user is invited. This should
be retrieved from the ``m.room.join_rules`` state event.
example: "public"
room_name:
type: string
description: |-
The name of the room to which the user is invited. This should be retrieved
from the ``m.room.name`` state event.
example: "Bob's Emporium of Messages"
sender_display_name:
type: string
description: The display name of the user ID initiating the invite.
example: "Bob Smith"
sender_avatar_url:
type: string
description: The Content URI for the avatar of the user ID initiating the invite.
example: "mxc://example.org/an0th3rM3dia"
required: ["medium", "address", "room_id", "sender"]
responses:
200:
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: |
The generated token. Must be a string consisting of the
characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed
255 characters and it must not be empty.
public_keys:
type: array
description: |
A list of [server's long-term public key, generated ephemeral
public key].
items:
type: string
display_name:
type: string
description: The generated (redacted) display_name.
required: ['token', 'public_keys', 'display_name']
example:
application/json: {
"token": "sometoken",
"public_keys": [
"serverpublickey",
"ephemeralpublickey"
],
"display_name": "f...@b..."
}
400:
description: |
An error has occured.
If the 3pid is already bound to a Matrix user ID, the error code
will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the
error code will be ``M_UNRECOGNIZED``.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "Binding already known",
"mxid": "@alice:example.com"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

2
api/push-gateway/push_notifier.yaml
View file

@ -57,7 +57,7 @@ paths:
type: object
example: {
"notification": {
"id": "$3957tyerfgewrf384",
"event_id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",

2
api/server-server/backfill.yaml
View file

@ -64,7 +64,7 @@ paths:
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing

10
api/server-server/definitions/keys.yaml
View file

@ -94,6 +94,12 @@ properties:
type: integer
format: int64
description: |-
POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
timestamp are no longer valid.
POSIX timestamp when the list of valid keys should be refreshed. This field MUST
be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST
be considered invalid, depending on the `room version specification`_.
Servers MUST use the lesser of this field and 7 days into the future when
determining if a key is valid. This is to avoid a situation where an attacker
publishes a key which is valid for a significant amount of time without a way
for the homeserver owner to revoke it.
example: 1052262000000

4
api/server-server/definitions/pdu_v3.yaml
View file

@ -20,6 +20,10 @@ allOf:
- $ref: "unsigned_pdu_base.yaml"
- type: object
properties:
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def/456+oldevent"
auth_events:
type: array
items:

47
api/server-server/definitions/pdu_v4.yaml Normal file
View file

@ -0,0 +1,47 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
title: Persistent Data Unit
description: A persistent data unit (event) for room version 4 and beyond.
example:
$ref: "../examples/pdu_v4.json"
allOf:
- $ref: "pdu_v3.yaml"
- type: object
properties:
redacts:
type: string
description: For redaction events, the ID of the event being redacted.
example: "$def_456-oldevent"
auth_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the authorization events that would
allow this event to be in the room.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
prev_events:
type: array
items:
type: string
description: Event ID.
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

32
api/server-server/definitions/single_pdu_transaction.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
allOf:
- $ref: "transaction.yaml"
properties:
pdus:
type: array
description: |-
A single PDU. Note that events have a different format depending on the room
version - check the `room version specification`_ for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ['origin', 'origin_server_ts', 'pdus']

33
api/server-server/definitions/unlimited_pdu_transaction.yaml Normal file
View file

@ -0,0 +1,33 @@
# Copyright 2019 The Matrix.org Foundation C.I.C.
#
# 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.
type: object
allOf:
- $ref: "transaction.yaml"
properties:
pdus:
type: array
description: |-
List of persistent updates to rooms. Note that events have a different format
depending on the room version - check the `room version specification`_ for
precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ['origin', 'origin_server_ts', 'pdus']

2
api/server-server/events.yaml
View file

@ -156,4 +156,4 @@ paths:
200:
description: A transaction containing a single PDU which is the event requested.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/single_pdu_transaction.yaml"

3
api/server-server/examples/pdu_v3.json
View file

@ -15,5 +15,6 @@
"prev_events": [
"$base64encodedeventid",
"$adifferenteventid"
]
],
"redacts": "$some/old+event"
}

12
api/server-server/examples/pdu_v4.json Normal file
View file

@ -0,0 +1,12 @@
{
"$ref": "pdu_v3.json",
"auth_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"prev_events": [
"$urlsafe_base64_encoded_eventid",
"$a-different-event-id"
],
"redacts": "$some-old_event"
}

73
api/server-server/invites-v1.yaml
View file

@ -82,35 +82,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
@ -118,26 +92,6 @@ paths:
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
},
"content": {
"membership": "invite"
},
@ -180,24 +134,9 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
},
"content": {
"membership": "invite"

73
api/server-server/invites-v2.yaml
View file

@ -83,35 +83,9 @@ paths:
identify the room. The recommended events to include are the join rules,
canonical alias, avatar, and name of the room.
items:
type: object
title: Invite Room State Event
properties:
type:
type: string
description: The type of event.
example: "m.room.join_rules"
state_key:
type: string
description: The state key for the event. May be an empty string.
example: ""
content:
type: object
description: The content for the event.
sender:
type: string
description: The sender of the event.
example: "@someone:matrix.org"
required: ['type', 'state_key', 'content', 'sender']
example: [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
}
]
$ref: "../../event-schemas/schema/stripped_state.yaml"
example:
$ref: "../../event-schemas/examples/invite_room_state.json"
required: ['room_version', 'event']
example: {
"room_version": "2",
@ -130,25 +104,7 @@ paths:
"ed25519:key_version": "SomeSignatureHere"
},
}
},
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
}
}
responses:
200:
@ -174,24 +130,9 @@ paths:
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
"type": "m.room.join_rules",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"join_rule": "public"
}
},
{
"type": "m.room.name",
"sender": "@someone:matrix.org",
"state_key": "",
"content": {
"name": "Cool New Room"
}
}
]
"invite_room_state": {
"$ref": "../../../event-schemas/examples/invite_room_state.json"
}
},
"content": {
"membership": "invite"

8
api/server-server/keys_query.yaml
View file

@ -44,8 +44,10 @@ paths:
type: string
description: |-
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
opt to return all keys, not just the requested one. The key ID to
look up.
When excluded, the trailing slash on this endpoint is optional.
required: false
x-example: "ed25519:abc123"
- in: query
@ -53,7 +55,7 @@ paths:
type: integer
format: int64
description: |-
A millisecond POSIX timestamp in milliseconds indicating when the returned
A millisecond POSIX timestamp in milliseconds indicating when the returned
certificates will need to be valid until to be useful to the requesting server.
If not supplied, the current time as determined by the notary server is used.
@ -114,7 +116,7 @@ paths:
format: int64
description: |-
A millisecond POSIX timestamp in milliseconds indicating when
the returned certificates will need to be valid until to be
the returned certificates will need to be valid until to be
useful to the requesting server.
If not supplied, the current time as determined by the notary

2
api/server-server/keys_server.yaml
View file

@ -51,6 +51,8 @@ paths:
**Deprecated**. Servers should not use this parameter and instead
opt to return all keys, not just the requested one. The key ID to
look up.
When excluded, the trailing slash on this endpoint is optional.
required: false
x-example: "ed25519:abc123"
deprecated: true

1
api/server-server/leaving.yaml
View file

@ -57,7 +57,6 @@ paths:
`room version specification`_ for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
schema:
schema:
type: object
properties:

6
api/server-server/query.yaml
View file

@ -81,7 +81,7 @@ paths:
servers:
type: array
description: |-
An array of server names that are likely to hold the given room. This
An array of server names that are likely to hold the given room. This
list may or may not include the server answering the query.
items:
type: string
@ -128,7 +128,7 @@ paths:
x-example: "@someone:example.org"
- in: query
name: field
type: enum
type: string
enum: ['displayname', 'avatar_url']
description: |-
The field to query. If specified, the server will only return the given field
@ -139,7 +139,7 @@ paths:
description: |-
The profile for the user. If a ``field`` is specified in the request, only the
matching field should be included in the response. If no ``field`` was specified,
the response should include the fields of the user's profile that can be made
the response should include the fields of the user's profile that can be made
public, such as the display name and avatar.
If the user does not have a particular field set on their profile, the server

3
api/server-server/user_devices.yaml
View file

@ -42,7 +42,6 @@ paths:
description: |-
The user ID to retrieve devices for. Must be a user local to the
receiving homeserver.
required: true
x-example: "@alice:example.org"
responses:
200:
@ -82,4 +81,4 @@ paths:
description: Optional display name for the device.
example: "Alice's Mobile Phone"
required: ['device_id', 'keys']
required: ['user_id', 'stream_id', 'devices']
required: ['user_id', 'stream_id', 'devices']

46
api/server-server/user_keys.yaml
View file

@ -63,7 +63,7 @@ paths:
- one_time_keys
responses:
200:
description: The claimed keys
description: The claimed keys.
schema:
type: object
properties:
@ -72,30 +72,42 @@ paths:
description: |-
One-time keys for the queried devices. A map from user ID, to a
map from devices to a map from ``<algorithm>:<key_id>`` to the key object.
See the Client-Server Key Algorithms section for more information on
the Key Object format.
additionalProperties:
type: object
additionalProperties:
type:
- string
- object
required: ['one_time_keys']
examples:
application/json: {
"one_time_keys": {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25518:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
- type: object
title: KeyObject
properties:
key:
type: string
description: The key, encoded using unpadded base64.
signatures:
type: object
description: |-
Signature for the device. Mapped from user ID to signature object.
additionalProperties:
type: string
required: ['key', 'signatures']
example: {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
}
}
}
required: ['one_time_keys']
"/user/keys/query":
post:
summary: Download device identity keys.
@ -168,8 +180,8 @@ paths:
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
"m.olm.v1.curve25519-aes-sha2",
"m.megolm.v1.aes-sha2"
],
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",

1
api/server-server/version.yaml
View file

@ -27,6 +27,7 @@ paths:
get:
summary: Get the implementation name and version of this homeserver.
description: Get the implementation name and version of this homeserver.
operationId: getVersion
responses:
200:
description:

1
api/server-server/wellknown.yaml
View file

@ -29,6 +29,7 @@ paths:
Gets information about the delegated server for server-server communication
between Matrix homeservers. Servers should follow 30x redirects, carefully
avoiding redirect loops, and use normal X.509 certificate validation.
operationId: getWellKnown
responses:
200:
description:

19
changelogs/application_service.rst
View file

@ -1,3 +1,22 @@
r0.1.2
======
Spec Clarifications
-------------------
- Clearer wording for the legacy routes section. (`#2160 <https://github.com/matrix-org/matrix-doc/issues/2160>`_)
r0.1.1
======
Spec Clarifications
-------------------
- Change examples to use example.org instead of a real domain. (`#1650 <https://github.com/matrix-org/matrix-doc/issues/1650>`_)
- Add missing definition for how appservices verify requests came from a homeserver. (`#2037 <https://github.com/matrix-org/matrix-doc/issues/2037>`_)
r0.1.0
======

82
changelogs/client_server.rst
View file

@ -1,3 +1,85 @@
r0.5.0
======
Breaking Changes
----------------
- Add a new ``submit_url`` field to the responses of ``/requestToken`` which older clients will not be able to handle correctly. (`#2101 <https://github.com/matrix-org/matrix-doc/issues/2101>`_)
Deprecations
------------
- Remove references to presence lists. (`#1817 <https://github.com/matrix-org/matrix-doc/issues/1817>`_)
New Endpoints
-------------
- ``GET /account_data`` routes. (`#1873 <https://github.com/matrix-org/matrix-doc/issues/1873>`_)
Backwards Compatible Changes
----------------------------
- Add megolm session export format. (`#1701 <https://github.com/matrix-org/matrix-doc/issues/1701>`_)
- Add support for advertising experimental features to clients. (`#1786 <https://github.com/matrix-org/matrix-doc/issues/1786>`_)
- Add a generic SSO login API. (`#1789 <https://github.com/matrix-org/matrix-doc/issues/1789>`_)
- Add a mechanism for servers to redirect clients to an alternative homeserver after logging in. (`#1790 <https://github.com/matrix-org/matrix-doc/issues/1790>`_)
- Add room version upgrades. (`#1791 <https://github.com/matrix-org/matrix-doc/issues/1791>`_, `#1875 <https://github.com/matrix-org/matrix-doc/issues/1875>`_)
- Support optional features by having clients query for capabilities. (`#1829 <https://github.com/matrix-org/matrix-doc/issues/1829>`_, `#1879 <https://github.com/matrix-org/matrix-doc/issues/1879>`_)
- Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them. (`#1874 <https://github.com/matrix-org/matrix-doc/issues/1874>`_)
- Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs. (`#1908 <https://github.com/matrix-org/matrix-doc/issues/1908>`_)
- Add a ``.m.rule.tombstone`` default push rule for room ugprade notifications. (`#2020 <https://github.com/matrix-org/matrix-doc/issues/2020>`_)
- Add support for sending server notices to clients. (`#2026 <https://github.com/matrix-org/matrix-doc/issues/2026>`_)
- Add MSISDN (phone number) support to User-Interactive Authentication. (`#2030 <https://github.com/matrix-org/matrix-doc/issues/2030>`_)
- Add the option to lazy-load room members for increased client performance. (`#2035 <https://github.com/matrix-org/matrix-doc/issues/2035>`_)
- Add ``id_server`` to ``/deactivate`` and ``/3pid/delete`` endpoints to unbind from a specific identity server. (`#2046 <https://github.com/matrix-org/matrix-doc/issues/2046>`_)
- Add support for Olm sessions becoming un-stuck. (`#2059 <https://github.com/matrix-org/matrix-doc/issues/2059>`_)
- Add interactive device verification, including a common framework for device verification. (`#2072 <https://github.com/matrix-org/matrix-doc/issues/2072>`_)
Spec Clarifications
-------------------
- Change examples to use example.org instead of a real domain. (`#1650 <https://github.com/matrix-org/matrix-doc/issues/1650>`_)
- Clarify that ``state_default`` in ``m.room.power_levels`` always defaults to 50. (`#1656 <https://github.com/matrix-org/matrix-doc/issues/1656>`_)
- Add missing ``status_msg`` to ``m.presence`` schema. (`#1744 <https://github.com/matrix-org/matrix-doc/issues/1744>`_)
- Fix various spelling mistakes throughout the specification. (`#1838 <https://github.com/matrix-org/matrix-doc/issues/1838>`_, `#1853 <https://github.com/matrix-org/matrix-doc/issues/1853>`_, `#1860 <https://github.com/matrix-org/matrix-doc/issues/1860>`_, `#1933 <https://github.com/matrix-org/matrix-doc/issues/1933>`_, `#1969 <https://github.com/matrix-org/matrix-doc/issues/1969>`_, `#1988 <https://github.com/matrix-org/matrix-doc/issues/1988>`_, `#1989 <https://github.com/matrix-org/matrix-doc/issues/1989>`_, `#1991 <https://github.com/matrix-org/matrix-doc/issues/1991>`_, `#1992 <https://github.com/matrix-org/matrix-doc/issues/1992>`_)
- Add the missing ``m.push_rules`` event schema. (`#1889 <https://github.com/matrix-org/matrix-doc/issues/1889>`_)
- Clarify how modern day local echo is meant to be solved by clients. (`#1891 <https://github.com/matrix-org/matrix-doc/issues/1891>`_)
- Clarify that ``width`` and ``height`` are required parameters on ``/_matrix/media/r0/thumbnail/{serverName}/{mediaId}``. (`#1975 <https://github.com/matrix-org/matrix-doc/issues/1975>`_)
- Clarify how ``m.login.dummy`` can be used to disambiguate login flows. (`#1999 <https://github.com/matrix-org/matrix-doc/issues/1999>`_)
- Remove ``prev_content`` from the redaction algorithm's essential keys list. (`#2016 <https://github.com/matrix-org/matrix-doc/issues/2016>`_)
- Fix the ``third_party_signed`` definitions for the join APIs. (`#2025 <https://github.com/matrix-org/matrix-doc/issues/2025>`_)
- Clarify why User Interactive Auth is used on password changes and how access tokens are handled. (`#2027 <https://github.com/matrix-org/matrix-doc/issues/2027>`_)
- Clarify that devices are deleted upon logout. (`#2028 <https://github.com/matrix-org/matrix-doc/issues/2028>`_)
- Add ``M_NOT_FOUND`` error definition for deleting room aliases. (`#2029 <https://github.com/matrix-org/matrix-doc/issues/2029>`_)
- Add missing ``reason`` to ``m.call.hangup``. (`#2031 <https://github.com/matrix-org/matrix-doc/issues/2031>`_)
- Clarify how redactions affect room state. (`#2032 <https://github.com/matrix-org/matrix-doc/issues/2032>`_)
- Clarify that ``FAIL_ERROR`` in autodiscovery is not limited to just homeservers. (`#2036 <https://github.com/matrix-org/matrix-doc/issues/2036>`_)
- Fix example ``Content-Type`` for ``/media/upload`` request. (`#2041 <https://github.com/matrix-org/matrix-doc/issues/2041>`_)
- Clarify that login flows are meant to be completed in order. (`#2042 <https://github.com/matrix-org/matrix-doc/issues/2042>`_)
- Clarify that clients should not send read receipts for their own messages. (`#2043 <https://github.com/matrix-org/matrix-doc/issues/2043>`_)
- Use consistent examples of events throughout the specification. (`#2051 <https://github.com/matrix-org/matrix-doc/issues/2051>`_)
- Clarify which push rule condition kinds exist. (`#2052 <https://github.com/matrix-org/matrix-doc/issues/2052>`_)
- Clarify the required fields on ``m.file`` (and similar) messages. (`#2053 <https://github.com/matrix-org/matrix-doc/issues/2053>`_)
- Clarify that User-Interactive Authentication stages cannot be attempted more than once. (`#2054 <https://github.com/matrix-org/matrix-doc/issues/2054>`_)
- Clarify which parameters apply in what scenarios on ``/register``. (`#2055 <https://github.com/matrix-org/matrix-doc/issues/2055>`_)
- Clarify how to interpret changes of ``membership`` over time. (`#2056 <https://github.com/matrix-org/matrix-doc/issues/2056>`_)
- Clarify exactly what invite_room_state consists of. (`#2067 <https://github.com/matrix-org/matrix-doc/issues/2067>`_)
- Clarify how the content repository works, and what it is used for. (`#2068 <https://github.com/matrix-org/matrix-doc/issues/2068>`_)
- Clarify the order events in chunk are returned in for ``/messages``. (`#2069 <https://github.com/matrix-org/matrix-doc/issues/2069>`_)
- Clarify the key object definition for the key management API. (`#2083 <https://github.com/matrix-org/matrix-doc/issues/2083>`_)
- Reorganize information about events into a common section. (`#2087 <https://github.com/matrix-org/matrix-doc/issues/2087>`_)
- De-duplicate ``/state/<event_type>`` endpoints, clarifying that the ``<state_key>`` is optional. (`#2088 <https://github.com/matrix-org/matrix-doc/issues/2088>`_)
- Clarify when and where CORS headers should be returned. (`#2089 <https://github.com/matrix-org/matrix-doc/issues/2089>`_)
- Clarify when authorization and rate-limiting are not applicable. (`#2090 <https://github.com/matrix-org/matrix-doc/issues/2090>`_)
- Clarify that ``/register`` must produce valid Matrix User IDs. (`#2091 <https://github.com/matrix-org/matrix-doc/issues/2091>`_)
- Clarify how ``unread_notifications`` is calculated. (`#2097 <https://github.com/matrix-org/matrix-doc/issues/2097>`_)
- Clarify what a "module" is and update feature profiles for clients. (`#2098 <https://github.com/matrix-org/matrix-doc/issues/2098>`_)
r0.4.0
======

1
changelogs/client_server/newsfragments/1701.feature
View file

@ -1 +0,0 @@
Documented megolm session export format.

1
changelogs/client_server/newsfragments/1744.clarification
View file

@ -1 +0,0 @@
Add missing status_msg to m.presence schema.

1
changelogs/client_server/newsfragments/1786.feature
View file

@ -1 +0,0 @@
Add support for advertising experimental features to clients.

1
changelogs/client_server/newsfragments/1789.feature
View file

@ -1 +0,0 @@
Add a generic SSO login API.

1
changelogs/client_server/newsfragments/1790.feature
View file

@ -1 +0,0 @@
Add a mechanism for servers to redirect clients to an alternative homeserver after logging in.

1
changelogs/client_server/newsfragments/1791.feature
View file

@ -1 +0,0 @@
Add room version upgrades.

1
changelogs/client_server/newsfragments/1817.deprecation
View file

@ -1 +0,0 @@
Remove references to presence lists.

1
changelogs/client_server/newsfragments/1829.feature
View file

@ -1 +0,0 @@
Support optional features by having clients query for capabilities.

1
changelogs/client_server/newsfragments/1838.clarification
View file

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1853.clarification
View file

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1860.clarification
View file

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/1873.new
View file

@ -1 +0,0 @@
``GET /account_data`` routes.

1
changelogs/client_server/newsfragments/1874.feature
View file

@ -1 +0,0 @@
Add ``M_RESOURCE_LIMIT_EXCEEDED`` as an error code for when homeservers exceed limits imposed on them.

1
changelogs/client_server/newsfragments/1875.feature
View file

@ -1 +0,0 @@
Add room version upgrades.

1
changelogs/client_server/newsfragments/1879.feature
View file

@ -1 +0,0 @@
Support optional features by having clients query for capabilities.

1
changelogs/client_server/newsfragments/1889.clarification
View file

@ -1 +0,0 @@
Add the missing `m.push_rules` event schema.

1
changelogs/client_server/newsfragments/1903.feature
View file

@ -1 +0,0 @@
Emit ``M_UNSUPPORTED_ROOM_VERSION`` error codes where applicable on ``/createRoom`` and ``/invite`` APIs.

1
changelogs/client_server/newsfragments/1933.clarification
View file

@ -1 +0,0 @@
Fix various spelling mistakes throughout the specification.

1
changelogs/client_server/newsfragments/2125.clarification Normal file
View file

@ -0,0 +1 @@
Add missing format fields to ``m.room.message$m.notice`` schema.

1
changelogs/client_server/newsfragments/2129.clarification Normal file
View file

@ -0,0 +1 @@
Remove "required" designation from the ``url`` field of certain ``m.room.message`` msgtypes.

1
changelogs/client_server/newsfragments/2131.clarification Normal file
View file

@ -0,0 +1 @@
Fix typo in key verification framework section.

1
changelogs/client_server/newsfragments/2132.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the distinction between ``m.key.verification.start`` and its ``m.sas.v1`` variant.

1
changelogs/client_server/newsfragments/2133.clarification Normal file
View file

@ -0,0 +1 @@
Fix link to Olm signing specification.

1
changelogs/client_server/newsfragments/2136.clarification Normal file
View file

@ -0,0 +1 @@
Fix various typos throughout the specification.

1
changelogs/client_server/newsfragments/2148.misc Normal file
View file

@ -0,0 +1 @@
Fix a small duplicated "as".

1
changelogs/client_server/newsfragments/2152.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the conditions for the ``.m.rule.room_one_to_one`` push rule.

1
changelogs/client_server/newsfragments/2157.clarification Normal file
View file

@ -0,0 +1 @@
Clarify the encryption algorithms supported by the device of the device keys example.

1
changelogs/client_server/newsfragments/2204.clarification Normal file
View file

@ -0,0 +1 @@
Clarify that ``/rooms/:roomId/event/:eventId`` returns a Matrix error.

Some files were not shown because too many files have changed in this diff Show more