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

Merge branch 'master' into travis/msc/integrations/openid

Browse source
This commit is contained in:
Travis Ralston 2020-08-21 08:14:28 -06:00
commit df74c7dbe3
362 changed files with 18461 additions and 2711 deletions
Download patch file Download diff file Expand all files Collapse all files

16
.buildkite/pipeline.yaml Normal file
View file

@ -0,0 +1,16 @@
steps:
- label: ":books: Build spec"
command:
- python3 -m venv env
- env/bin/pip install -r scripts/requirements.txt
- ". env/bin/activate; scripts/generate-matrix-org-assets"
artifact_paths:
- assets.tar.gz
plugins:
- docker#v3.0.1:
image: "python:3.6"
- label: "rebuild matrix.org"
trigger: "matrix-dot-org"
async: true
branches: "master"

4
.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:
@ -121,4 +121,4 @@ workflows:
notify:
webhooks:
- url: https://giles.cadair.com/circleci
- url: https://giles.cadair.dev/circleci

2
.github/FUNDING.yml vendored Normal file
View file

@ -0,0 +1,2 @@
patreon: matrixdotorg
liberapay: matrixdotorg

19
.github/PULL_REQUEST_TEMPLATE/ready-proposal.md vendored Normal file
View file

@ -0,0 +1,19 @@
---
name: Proposal ready for review
about: A proposal that is ready for review by the core team and community.
title: ''
labels: proposal, proposal-in-review
assignees: ''
---
<!-- Put your "rendered" link here -->
### Pull Request Checklist
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
* [ ] Pull request includes ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
* [ ] Pull request title and file name include this PR's number as the MSC number.

16
.github/PULL_REQUEST_TEMPLATE/spec-change.md vendored Normal file
View file

@ -0,0 +1,16 @@
---
name: Spec clarification/not a proposal
about: A change that's not a spec proposal, such as a clarification to the spec itself.
title: ''
labels: ''
assignees: ''
---
### Pull Request Checklist
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#other-changes)

20
.github/PULL_REQUEST_TEMPLATE/wip-proposal.md vendored Normal file
View file

@ -0,0 +1,20 @@
---
name: WIP Proposal
about: A proposal that isn't quite ready for formal review yet.
title: '[WIP] Your Proposal Title'
labels: proposal
assignees: ''
---
<!-- Put your "rendered" link here -->
### Pull Request Checklist
<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-doc/blob/master/CONTRIBUTING.rst#sign-off)
* [ ] A ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
* [ ] Ask in [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to get this marked as ready for review, once it is ready for review.

1
.gitignore vendored
View file

@ -12,3 +12,4 @@
*.swp
_rendered.rst
/.vscode/
/.idea/

36
CONTRIBUTING.rst
View file

@ -13,7 +13,7 @@ https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rs
Python code within the ``matrix-doc`` project should follow the same style as
synapse, which is documented at
https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.
https://github.com/matrix-org/synapse/tree/master/docs/code_style.md.
Matrix-doc workflows
--------------------
@ -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

8
README.rst
View file

@ -46,7 +46,7 @@ To use the scripts, it is best to create a Python 3.4+ virtualenv as follows::
virtualenv -p python3 env
env/bin/pip install -r scripts/requirements.txt
(Benjamin Synders has contributed a script for `Nix`_ users, which can be
(Benjamin Saunders has contributed a script for `Nix`_ users, which can be
invoked with ``nix-shell scripts/contrib/shell.nix``.)
.. TODO: Possibly we need some libs installed; should record what they are.
@ -66,12 +66,14 @@ The above will write the rendered version of the specification to
Windows users
~~~~~~~~~~~~~
The ``source`` program does not exist on Windows, so instead run one of the
``activate`` files in ``.\env\Scripts\`` to activate the virtual environment.
If you're on Windows Vista or higher, be sure that the "Symbolic Links"
option was selected when installing Git prior to cloning this repository. If
you're still seeing errors about files not being found it is likely because
the symlink at ``api/client-server/definitions/event-schemas`` looks like a
file. To correct the problem, open an Administrative/Elevated shell in your
file. To correct the problem, open an Administrative/Elevated Command Prompt in your
cloned matrix-doc directory and run the following::
cd api\client-server\definitions
@ -138,4 +140,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.

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

@ -50,16 +50,15 @@ paths:
x-example: "35"
- in: body
name: body
description: A list of events.
description: Transaction information
schema:
type: object
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
properties:
events:
type: array

2
api/client-server/admin.yaml
View file

@ -82,7 +82,7 @@ paths:
devices:
type: object
description: |-
Each key is an identitfier for one of the user's devices.
Each key is an identifier for one of the user's devices.
additionalProperties:
type: object
title: DeviceInfo

326
api/client-server/administrative_contact.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.
@ -89,13 +90,25 @@ paths:
- User data
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
description: |-
Adds contact information to the user's account.
This endpoint is deprecated in favour of the more specific ``/3pid/add``
and ``/3pid/bind`` endpoints.
.. Note::
Previously this endpoint supported a ``bind`` parameter. This parameter
has been removed, making this endpoint behave as though it was ``false``.
This results in this endpoint being an equivalent to ``/3pid/bind`` rather
than dual-purpose.
operationId: post3PIDs
deprecated: true
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -110,33 +123,51 @@ paths:
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "sid"]
bind:
type: boolean
description: |-
Whether the homeserver should also bind this third party
identifier to the account's Matrix ID with the passed identity
server. Default: ``false``.
x-example: true
required: ["client_secret", "id_server", "id_access_token", "sid"]
required: ["three_pid_creds"]
example: {
"three_pid_creds": {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
},
"bind": false
}
}
responses:
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 (without the requirement
for an access token). 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:
@ -148,21 +179,142 @@ paths:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/add":
post:
summary: Adds contact information to the user's account.
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
Adds contact information to the user's account. Homeservers should use 3PIDs added
through this endpoint for password resets instead of relying on the identity server.
Homeservers should prevent the caller from adding a 3PID to their account if it has
already been added to another user's account on the homeserver.
operationId: add3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
allOf:
- $ref: "definitions/auth_data.yaml"
client_secret:
type: string
description: The client secret used in the session with the homeserver.
sid:
type: string
description: The session identifier given by the homeserver.
required: ["client_secret", "sid"]
example: {
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
"/account/3pid/bind":
post:
summary: Binds a 3PID to the user's account through an Identity Service.
description: |-
Binds a 3PID to the user's account through the specified identity server.
Homeservers should not prevent this request from succeeding if another user
has bound the 3PID. Homeservers should simply proxy any errors received by
the identity server to the caller.
Homeservers should track successful binds so they can be unbound later.
operationId: bind3PID
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
client_secret:
type: string
description: The client secret used in the session with the identity server.
id_server:
type: string
description: The identity server to use.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server.
sid:
type: string
description: The session identifier given by the identity server.
required: ["client_secret", "id_server", "id_access_token", "sid"]
example: {
"id_server": "example.org",
"id_access_token": "abc123_OpaqueString",
"sid": "abc123987",
"client_secret": "d0n'tT3ll"
}
responses:
200:
description: The addition was successful.
examples:
application/json: {}
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/3pid/delete":
post:
summary: Deletes a third party identifier from the user's account
description: |-
Removes a third party identifier from the user's account. This might not
cause an unbind of the identifier from the identity server.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: delete3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
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 +332,116 @@ 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/unbind":
post:
summary: Removes a user's third party identifier from an identity server.
description: |-
Removes a user's third party identifier from the provided identity server
without removing it from the homeserver.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
parameter because the homeserver is expected to sign the request to the
identity server instead.
operationId: unbind3pidFromAccount
security:
- accessToken: []
parameters:
- in: body
name: body
required: true
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.
enum: ["email", "msisdn"]
example: "email"
address:
type: string
description: The third party address being removed.
example: "example@example.org"
required: ['medium', 'address']
responses:
200:
description: |-
The identity server has disassociated the third party identifier from the
user.
schema:
type: object
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 identity server was able to unbind
the 3PID. ``success`` indicates that the identity 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 should validate
the email itself, either by sending a validation email itself or by using
a service it has control over.
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
@ -229,7 +456,9 @@ paths:
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid.
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
@ -241,34 +470,25 @@ 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 should validate
the phone number itself, either by sending a validation message itself or by using
a service it has control over.
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
@ -283,7 +503,9 @@ paths:
400:
description: |-
The third party identifier is already in use on the homeserver, or
the request was invalid.
the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:

158
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,11 @@ 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 overriding the file name
description: |-
This will download content from the content repository (same as
the previous endpoint) but replace the target file name with the one
provided by the caller.
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
@ -148,8 +190,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 +199,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 +209,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 +235,10 @@ 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
description: |-
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 +246,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,32 +260,36 @@ 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
x-example: false
required: false
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
true if not provided.
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 true if not provided.
responses:
200:
description: "A thumbnail of the requested content."
@ -238,6 +300,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:
@ -247,6 +343,16 @@ paths:
"/preview_url":
get:
summary: "Get information about a URL for a client"
description: |-
Get information about a URL for the client. Typically this is called when a
client sees a URL in a message and wants to render a preview for the user.
.. Note::
Clients should consider avoiding this endpoint for URLs posted in encrypted
rooms. Encrypted rooms often contain more sensitive information the users
do not want to share with the homeserver, and this can mean that the URLs
being shared should also not be shared with the homeserver.
operationId: getUrlPreview
produces: ["application/json"]
security:
@ -256,7 +362,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 +390,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 +434,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.

25
api/client-server/create_room.yaml
View file

@ -38,20 +38,26 @@ paths:
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
0. A default ``m.room.power_levels`` event, giving the room creator
1. The ``m.room.create`` event itself. Must be the first event in the
room.
2. An ``m.room.member`` event for the creator to join the room. This is
needed so the remaining events can be sent.
3. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
2. Events listed in ``initial_state``, in the order that they are
5. Events listed in ``initial_state``, in the order that they are
listed.
3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
The available presets do the following with respect to room state:
@ -74,6 +80,7 @@ paths:
- in: body
name: body
description: The desired room configuration.
required: true
schema:
type: object
example: {
@ -139,6 +146,12 @@ paths:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
# TODO: Link to Identity Service spec when it eixsts
@ -146,7 +159,7 @@ paths:
address:
type: string
description: The invitee's third party identifier.
required: ["id_server", "medium", "address"]
required: ["id_server", "id_access_token", "medium", "address"]
room_version:
type: string
description: |-

3
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: |-
@ -47,6 +47,7 @@ properties:
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
signatures:
type: object
title: Signatures
description: |-
Signatures for the device key object. A map from user ID, to a map from
``<algorithm>:<device_id>`` to the signature.

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

@ -59,7 +59,7 @@ properties:
description: Optional. The event that redacted this event, if any.
title: Event
type: object
title: Unsigned
title: UnsignedData
type: object
title: Event
type: object

50
api/client-server/definitions/key_backup_data.yaml Normal file
View file

@ -0,0 +1,50 @@
# 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: KeyBackupData
description: "The key data"
properties:
first_message_index:
description: |-
The index of the first message in the session that the key can decrypt.
type: integer
example: 1
forwarded_count:
description: |-
The number of times this key has been forwarded via key-sharing between devices.
type: integer
example: 0
is_verified:
description: |-
Whether the device backing up the key verified the device that the key
is from.
type: boolean
example: false
session_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in `Server-side key backups`_ for more information on the
expected format of the data.
type: object
example: {
"ephemeral": "base64+ephemeral+key",
"ciphertext": "base64+ciphertext+of+JSON+data",
"mac": "base64+mac+of+ciphertext"
}
required:
- first_message_index
- forwarded_count
- is_verified
- session_data

36
api/client-server/definitions/openid_token.yaml Normal file
View file

@ -0,0 +1,36 @@
# 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.
type: object
properties:
access_token:
type: string
description: |-
An access token the consumer may use to verify the identity of
the person who generated the token. This is given to the federation
API ``GET /openid/userinfo`` to verify the user's identity.
token_type:
type: string
description: The string ``Bearer``.
matrix_server_name:
type: string
description: |-
The homeserver domain the consumer should use when attempting to
verify the user's identity.
expires_in:
type: integer
description: |-
The number of seconds before this token expires and a new one must
be generated.
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']

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

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

@ -0,0 +1,36 @@
# 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.
This parameter is deprecated with a plan to be removed in a future specification
version for ``/account/password`` and ``/register`` requests.
example: "id.example.com"
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
Required if an ``id_server`` is supplied.

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

@ -0,0 +1,36 @@
# 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.
This parameter is deprecated with a plan to be removed in a future specification
version for ``/account/password`` and ``/register`` requests.
example: "id.example.com"
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
Required if an ``id_server`` is supplied.

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 (without the requirement
for an access token). 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'``

38
api/client-server/definitions/room_key_backup.yaml Normal file
View file

@ -0,0 +1,38 @@
# Copyright 2020 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: RoomKeyBackup
description: "The backed up keys for a room."
properties:
sessions:
type: object
description: "A map of session IDs to key data."
additionalProperties:
allOf:
- $ref: "key_backup_data.yaml"
example: {
"sessionid1": {
"first_message_index": 1,
"forwarded_count": 0,
"is_verified": true,
"session_data": {
"ephemeral": "base64+ephemeral+key",
"ciphertext": "base64+ciphertext+of+JSON+data",
"mac": "base64+mac+of+ciphertext"
}
}
}
required:
- sessions

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

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

@ -0,0 +1,45 @@
# 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
additionalProperties:
type: object
additionalProperties:
type: string
example: {
"example.org": {
"ed25519:0": "some9signature"
}
}
required: ["sender", "mxid", "token", "signatures"]

20
api/client-server/device_management.yaml
View file

@ -83,7 +83,7 @@ paths:
schema:
type: object
allOf:
- $ref: "definitions/client_device.yaml"
- $ref: "definitions/client_device.yaml"
examples:
application/json: {
"device_id": "QBUAZIFURK",
@ -119,9 +119,9 @@ paths:
display_name:
type: string
description: |-
The new display name for this device. If not given, the
display name is unchanged.
example: My other phone
The new display name for this device. If not given, the
display name is unchanged.
example: { "display_name": "My other phone" }
responses:
200:
description: The device was successfully updated.
@ -152,14 +152,16 @@ paths:
x-example: "QBUAZIFURK"
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
Additional authentication information for the
user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
responses:
200:
description: |-
@ -190,6 +192,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -201,10 +204,11 @@ paths:
description: A list of device IDs.
example: ["QBUAZIFURK", "AUIECTSRND"]
auth:
allOf:
- "$ref": "definitions/auth_data.yaml"
description: |-
Additional authentication information for the
user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
required:
- devices
responses:

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

@ -19,7 +19,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
@ -27,7 +27,7 @@ produces:
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/room/{roomAlias}":
"/directory/room/{roomAlias}":
put:
summary: Create a new mapping from room alias to room ID.
operationId: setRoomAlias
@ -129,7 +129,16 @@ paths:
description: |-
Remove a mapping of room alias to room ID.
Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
Servers may choose to implement additional access control checks here, for instance that
room aliases can only be deleted by their creator or a server administrator.
.. Note::
Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias``
state event in the room when an alias is removed. Servers which choose to update the
canonical alias event are recommended to, in addition to their other relevant permission
checks, delete the alias and return a successful response even if the user does not
have permission to update the ``m.room.canonical_alias`` event.
operationId: deleteRoomAlias
security:
- accessToken: []
@ -148,5 +157,81 @@ 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
"/rooms/{roomId}/aliases":
get:
summary: Get a list of local aliases on a given room.
description: |-
Get a list of aliases maintained by the local server for the
given room.
This endpoint can be called by users who are in the room (external
users receive an ``M_FORBIDDEN`` error response). If the room's
``m.room.history_visibility`` maps to ``world_readable``, any
user can call this endpoint.
Servers may choose to implement additional access control checks here,
such as allowing server administrators to view aliases regardless of
membership.
.. Note::
Clients are recommended not to display this list of aliases prominently
as they are not curated, unlike those listed in the ``m.room.canonical_alias``
state event.
operationId: getLocalAliases
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID to find local aliases of.
required: true
x-example: "!abc123:example.org"
responses:
200:
description: |-
The list of local aliases for the room.
examples:
application/json: {
"aliases": [
"#somewhere:example.com",
"#another:example.com",
"#hat_trick:example.com"
]
}
schema:
type: object
properties:
aliases:
type: array
description: The server's local aliases on the room. Can be empty.
items:
type: string
required: ['aliases']
403:
description: The user is not permitted to retrieve the list of local aliases for the room.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not a member of the room."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room directory

103
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: []
@ -56,6 +59,18 @@ paths:
description: |-
The maximum number of events to return. Default: 10.
x-example: 3
- in: query
name: filter
type: string
description: |-
A JSON ``RoomEventFilter`` to filter the returned events with. The
filter is only applied to ``events_before``, ``events_after``, and
``state``. It is not applied to the ``event`` itself. The filter may
be applied before or/and after the ``limit`` parameter - whichever the
homeserver prefers.
See `Filtering <#filtering>`_ for more information.
x-example: "66696p746572"
responses:
200:
description: The events and state surrounding the requested event.
@ -101,65 +116,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

2
api/client-server/filter.yaml
View file

@ -119,7 +119,7 @@ paths:
responses:
200:
description: |-
"The filter defintion"
The filter definition.
examples:
application/json: {
"room": {

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

@ -31,7 +31,8 @@ paths:
post:
summary: Start the requesting user participating in a particular room.
description: |-
*Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
*Note that this API requires a room ID, not alias.*
``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
This API starts a user participating in a particular room, if that user
is allowed to participate in that room. After this call, the client is
@ -40,10 +41,6 @@ paths:
After a user has joined a room, the room will appear as an entry in the
response of the |/initialSync|_ and |/sync|_ APIs.
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoomById
security:
- accessToken: []
@ -56,40 +53,17 @@ paths:
x-example: "!d41d8cd:matrix.org"
- in: body
name: third_party_signed
required: true
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"]
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If supplied, the homeserver must verify that it matches a pending
``m.room.third_party_invite`` event in the room, and perform
key validity checking if required by the event.
responses:
200:
description: |-
@ -108,7 +82,8 @@ paths:
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
You do not have permission to join the room. A meaningful ``errcode``
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
@ -136,10 +111,6 @@ paths:
After a user has joined a room, the room will appear as an entry in the
response of the |/initialSync|_ and |/sync|_ APIs.
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
operationId: joinRoom
security:
- accessToken: []
@ -161,47 +132,17 @@ paths:
x-example: ["matrix.org", "elsewhere.ca"]
- in: body
name: third_party_signed
required: true
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"]
allOf:
- $ref: "definitions/third_party_signed.yaml"
description: |-
If a ``third_party_signed`` was supplied, the homeserver must verify
that it matches a pending ``m.room.third_party_invite`` event in the
room, and perform key validity checking if required by the event.
responses:
200:
description: |-
@ -220,7 +161,8 @@ paths:
required: ["room_id"]
403:
description: |-
You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
You do not have permission to join the room. A meaningful ``errcode``
and description error text will be returned. Example reasons for rejection are:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.

924
api/client-server/key_backup.yaml Normal file
View file

@ -0,0 +1,924 @@
# Copyright 2019-2020 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 Client-Server Key Backup API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/room_keys/version":
post:
summary: Create a new backup.
description: |-
Creates a new backup.
operationId: postRoomKeysVersion
security:
- accessToken: []
parameters:
- in: body
name: version
description: "The backup configuration."
required: true
schema:
type: object
properties:
algorithm:
description: The algorithm used for storing backups.
type: string
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
example: "m.megolm_backup.v1.curve25519-aes-sha2"
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in `Server-side key backups`_ for more information on the
expected format of the data.
type: object
example: {
"public_key": "abcdefg",
"signatures": {
"@alice:example.org": {
"ed25519:deviceid": "signature"
}
}
}
required:
- algorithm
- auth_data
responses:
200:
description:
The version id of the new backup.
schema:
type: object
properties:
version:
type: string
description: The backup version. This is an opaque string.
example: "1"
required:
- version
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
get:
summary: Get information about the latest backup version.
description: |-
Get information about the latest backup version.
operationId: getRoomKeysVersionCurrent
security:
- accessToken: []
responses:
200:
description:
The information about the backup.
schema:
type: object
properties:
algorithm:
type: string
description: The algorithm used for storing backups.
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
example: "m.megolm_backup.v1.curve25519-aes-sha2"
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in `Server-side key backups`_ for more information on the
expected format of the data.
type: object
example: {
"public_key": "abcdefg",
"signatures": {
"@alice:example.org": {
"ed25519:deviceid": "signature"
}
}
}
count:
description: The number of keys stored in the backup.
type: integer
example: 42
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the ``etag`` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
example: "anopaquestring"
version:
type: string
description: The backup version.
example: "1"
required:
- algorithm
- auth_data
- count
- etag
- version
404:
description:
No backup exists.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "No current backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
"/room_keys/version/{version}":
get:
summary: Get information about an existing backup.
description: |-
Get information about an existing backup.
operationId: getRoomKeysVersion
security:
- accessToken: []
parameters:
- in: path
type: string
name: version
description: |-
The backup version to get, as returned in the ``version`` parameter
of the response in `POST /_matrix/client/r0/room_keys/version`_ or
this endpoint.
required: true
x-example: "1"
responses:
200:
description:
The information about the requested backup.
schema:
type: object
properties:
algorithm:
type: string
description: The algorithm used for storing backups.
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
example: "m.megolm_backup.v1.curve25519-aes-sha2"
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in `Server-side key backups`_ for more information on the
expected format of the data.
type: object
example: {
"public_key": "abcdefg",
"signatures": {
"@alice:example.org": {
"ed25519:deviceid": "signature"
}
}
}
count:
description: The number of keys stored in the backup.
type: integer
example: 42
etag:
description: |-
An opaque string representing stored keys in the backup.
Clients can compare it with the ``etag`` value they received
in the request of their last key storage request. If not
equal, another client has modified the backup.
type: string
example: "anopaquestring"
version:
type: string
description: The backup version.
example: "1"
required:
- algorithm
- auth_data
- count
- etag
- version
404:
description:
The backup specified does not exist.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
put:
summary: Update information about an existing backup.
description: |-
Update information about an existing backup. Only ``auth_data`` can be modified.
operationId: putRoomKeysVersion
security:
- accessToken: []
parameters:
- in: path
type: string
name: version
description: |-
The backup version to update, as returned in the ``version``
parameter in the response of `POST
/_matrix/client/r0/room_keys/version`_ or `GET
/_matrix/client/r0/room_keys/version/{version}`_.
required: true
x-example: "1"
- in: body
name: version
description: "The backup configuration"
required: true
schema:
type: object
properties:
algorithm:
description: |-
The algorithm used for storing backups. Must be the same as
the algorithm currently used by the backup.
type: string
enum: ["m.megolm_backup.v1.curve25519-aes-sha2"]
example: "m.megolm_backup.v1.curve25519-aes-sha2"
auth_data:
description: |-
Algorithm-dependent data. See the documentation for the backup
algorithms in `Server-side key backups`_ for more information on the
expected format of the data.
type: object
example: {
"public_key": "abcdefg",
"signatures": {
"@alice:example.org": {
"ed25519:deviceid": "signature"
}
}
}
version:
description: |-
The backup version. If present, must be the same as the
version in the path parameter.
type: string
example: "1"
required:
- algorithm
- auth_data
responses:
200:
description: The update succeeded.
schema:
type: object
properties: {}
400:
description: |-
A parameter was incorrect. For example, the ``algorithm`` does not
match the current backup algorithm, or the ``version`` in the body
does not match the ``version`` in the path.
examples:
application/json: {
"errcode": "M_INVALID_PARAM",
"error": "Algorithm does not match"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: The backup specified does not exist.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
delete:
summary: Delete an existing key backup.
description: |-
Delete an existing key backup. Both the information about the backup,
as well as all key data related to the backup will be deleted.
operationId: deleteRoomKeysVersion
security:
- accessToken: []
parameters:
- in: path
type: string
name: version
description: |-
The backup version to delete, as returned in the ``version``
parameter in the response of `POST
/_matrix/client/r0/room_keys/version`_ or `GET
/_matrix/client/r0/room_keys/version/{version}`_.
required: true
x-example: "1"
responses:
200:
description: |-
The delete succeeded, or the specified backup was previously
deleted.
schema:
type: object
properties: {}
404:
description: |-
The backup specified does not exist. If the backup was previously
deleted, the call should succeed rather than returning an error.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
"/room_keys/keys/{roomId}/{sessionId}":
put:
summary: Store a key in the backup.
description: |-
Store a key in the backup.
operationId: postRoomKeysKeyRoomIdSessionId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup in which to store the key. Must be the current backup.
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the key is for.
required: true
x-example: "!roomid:example.org"
- in: path
type: string
name: sessionId
description: The ID of the megolm session that the key is for.
required: true
x-example: "sessionid"
- in: body
name: data
description: "The key data."
required: true
schema:
"$ref": "definitions/key_backup_data.yaml"
responses:
200:
description: The update succeeded.
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
field.
examples:
application/json: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
get:
summary: Retrieve a key from the backup
description: |-
Retrieve a key from the backup.
operationId: getRoomKeysKeyRoomIdSessionId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to retrieve the key.
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the requested key is for.
required: true
x-example: "!roomid:example.org"
- in: path
type: string
name: sessionId
description: The ID of the megolm session whose key is requested.
required: true
x-example: "sessionid"
responses:
200:
description: The key data
schema:
"$ref": "definitions/key_backup_data.yaml"
404:
description: The key or backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Key not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
delete:
summary: Delete a key from the backup
description: |-
Delete a key from the backup.
operationId: deleteRoomKeysKeyRoomIdSessionId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to delete the key
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the specified key is for.
required: true
x-example: "!roomid:example.org"
- in: path
type: string
name: sessionId
description: The ID of the megolm session whose key is to be deleted.
required: true
x-example: "sessionid"
responses:
200:
description: The update succeeded
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
"/room_keys/keys/{roomId}":
put:
summary: Store several keys in the backup for a given room.
description: |-
Store a key in the backup.
operationId: postRoomKeysKeyRoomId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup in which to store the keys. Must be the current backup.
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the keys are for.
required: true
x-example: "!roomid:example.org"
- in: body
description: "The backup data"
name: backupData
required: true
schema:
$ref: "definitions/room_key_backup.yaml"
responses:
200:
description: The update succeeded
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
field.
examples:
application/json: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
get:
summary: Retrieve the keys from the backup for a given room
description: |-
Retrieve the keys from the backup for a given room
operationId: getRoomKeysKeyRoomId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to retrieve the key.
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the requested key is for.
required: true
x-example: "!roomid:example.org"
responses:
200:
description: |-
The key data. If no keys are found, then an object with an empty
``sessions`` property will be returned (``{"sessions": {}}``).
schema:
type: object
$ref: "definitions/room_key_backup.yaml"
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
delete:
summary: Delete a key from the backup
description: |-
Delete a key from the backup.
operationId: deleteRoomKeysKeyRoomId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to delete the key.
required: true
x-example: "1"
- in: path
type: string
name: roomId
description: The ID of the room that the specified key is for.
required: true
x-example: "!roomid:example.org"
responses:
200:
description: The update succeeded
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
"/room_keys/keys":
put:
summary: Store several keys in the backup.
description: |-
Store several keys in the backup.
operationId: postRoomKeysKey
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup in which to store the keys. Must be the current backup.
required: true
x-example: "1"
- in: body
description: "The backup data."
name: backupData
required: true
schema:
type: object
properties:
rooms:
type: object
description: |-
A map of room IDs to room key backup data.
additionalProperties:
allOf:
- $ref: "definitions/room_key_backup.yaml"
example: {
"!room:example.org": {
"sessions": {
"sessionid1": {
"first_message_index": 1,
"forwarded_count": 0,
"is_verified": true,
"session_data": {
"ephemeral": "base64+ephemeral+key",
"ciphertext": "base64+ciphertext+of+JSON+data",
"mac": "base64+mac+of+ciphertext"
}
}
}
}
}
required:
- rooms
responses:
200:
description: The update succeeded
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
403:
description: |-
The version specified does not match the current backup version.
The current version will be included in the ``current_version``
field.
examples:
application/json: {
"errcode": "M_WRONG_ROOM_KEYS_VERSION",
"error": "Wrong backup version.",
"current_version": "42"
}
schema:
"$ref": "definitions/errors/error.yaml"
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- End-to-end encryption
get:
summary: Retrieve the keys from the backup for a given room
description: |-
Retrieve the keys from the backup for a given room
operationId: getRoomKeysKeyRoomId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to retrieve the keys.
required: true
x-example: "1"
responses:
200:
description: |-
The key data. If no keys are found, then an object with an empty
``rooms`` property will be returned (``{"rooms": {}}``).
schema:
type: object
properties:
rooms:
type: object
description: |-
A map of room IDs to room key backup data.
additionalProperties:
allOf:
- $ref: "definitions/room_key_backup.yaml"
example: {
"!room:example.org": {
"sessions": {
"sessionid1": {
"first_message_index": 1,
"forwarded_count": 0,
"is_verified": true,
"session_data": {
"ephemeral": "base64+ephemeral+key",
"ciphertext": "base64+ciphertext+of+JSON+data",
"mac": "base64+mac+of+ciphertext"
}
}
}
}
}
404:
description: The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
delete:
summary: Delete a key from the backup
description: |-
Delete a key from the backup.
operationId: deleteRoomKeysKeyRoomId
security:
- accessToken: []
parameters:
- in: query
type: string
name: version
description: |-
The backup from which to delete the key
required: true
x-example: "1"
responses:
200:
description: The update succeeded
schema:
type: object
properties:
etag:
description: |-
The new etag value representing stored keys in the backup.
See ``GET /room_keys/version/{version}`` for more details.
type: string
example: "abcdefg"
count:
description: The number of keys stored in the backup
type: integer
example: 10
required:
- etag
- count
404:
description: |-
The backup was not found.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown backup version"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"

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

@ -41,6 +41,7 @@ paths:
name: keys
description: |-
The keys to be published
required: true
schema:
type: object
properties:
@ -56,29 +57,52 @@ 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:
The provided keys were sucessfully uploaded.
The provided keys were successfully uploaded.
schema:
type: object
properties:
@ -110,6 +134,7 @@ paths:
name: query
description: |-
Query defining the keys to be downloaded
required: true
schema:
type: object
properties:
@ -173,6 +198,7 @@ paths:
additionalProperties:
type: object
additionalProperties:
title: DeviceInformation
allOf:
- $ref: definitions/device_keys.yaml
properties:
@ -194,8 +220,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 +231,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":
@ -226,6 +252,7 @@ paths:
name: query
description: |-
Query defining the keys to be claimed
required: true
schema:
type: object
properties:
@ -246,14 +273,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 +291,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 +303,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":

3
api/client-server/kicking.yaml
View file

@ -77,7 +77,8 @@ paths:
type: object
403:
description: |-
You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
You do not have permission to kick the user from the room. A meaningful ``errcode`` and
description error text will be returned. Example reasons for rejections are:
- The kicker is not currently in the room.
- The kickee is not currently in the room.

93
api/client-server/list_public_rooms.yaml
View file

@ -218,97 +218,6 @@ paths:
200:
description: A list of the rooms on the server.
schema:
type: object
description: A list of the rooms on the server.
required: ["chunk"]
properties:
chunk:
title: "PublicRoomsChunks"
type: array
description: |-
A paginated chunk of public rooms.
items:
type: object
title: "PublicRoomsChunk"
required:
- room_id
- num_joined_members
- world_readable
- guest_can_join
properties:
aliases:
type: array
description: |-
Aliases of the room. May be empty.
items:
type: string
canonical_alias:
type: string
description: |-
The canonical alias of the room, if any.
name:
type: string
description: |-
The name of the room, if any.
num_joined_members:
type: integer
description: |-
The number of members joined to the room.
room_id:
type: string
description: |-
The ID of the room.
topic:
type: string
description: |-
The topic of the room, if any.
world_readable:
type: boolean
description: |-
Whether the room may be viewed by guest users without joining.
guest_can_join:
type: boolean
description: |-
Whether guest users may join the room and participate in it.
If they can, they will be subject to ordinary power level
rules like any other user.
avatar_url:
type: string
description: The URL for the room's avatar, if one is set.
next_batch:
type: string
description: |-
A pagination token for the response. The absence of this token
means there are no more results to fetch and the client should
stop paginating.
prev_batch:
type: string
description: |-
A pagination token that allows fetching previous results. The
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
application/json: {
"chunk": [
{
"aliases": ["#murrays:cheese.bar"],
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true
}
],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
$ref: "definitions/public_rooms_response.yaml"
tags:
- Room discovery

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

@ -82,6 +82,7 @@ paths:
parameters:
- in: body
name: body
required: true
schema:
type: object
example: {
@ -99,7 +100,6 @@ paths:
enum: ["m.login.password", "m.login.token"]
description: The login type being used.
identifier:
description: Identification information for the user.
"$ref": "definitions/user_identifier.yaml"
user:
type: string
@ -154,7 +154,7 @@ paths:
properties:
user_id:
type: string
description: The fully-qualified Matrix ID that has been registered.
description: The fully-qualified Matrix ID for the account.
access_token:
type: string
description: |-
@ -175,13 +175,13 @@ paths:
ID of the logged-in device. Will be the same as the
corresponding parameter in the request, if one was specified.
well_known:
type: object
description: |-
Optional client configuration provided by the server. If present,
clients SHOULD use the provided object to reconfigure themselves,
optionally validating the URLs within. This object takes the same
form as the one returned from .well-known autodiscovery.
"$ref": "definitions/wellknown/full.yaml"
allOf:
- "$ref": "definitions/wellknown/full.yaml"
400:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
@ -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:

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

@ -32,13 +32,14 @@ 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: []
responses:
200:
description: The access token used in the request was succesfully invalidated.
description: The access token used in the request was successfully invalidated.
schema:
type: object
properties: {}
@ -49,19 +50,22 @@ 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
token then takes over the account. This endpoint invalidates all access tokens for
the user, including the token used in the request, and therefore the attacker is
unable to take over the account in this way.
This endpoint does not use the `User-Interactive Authentication API`_ because
User-Interactive Authentication is designed to protect against attacks where the
someone gets hold of a single access token then takes over the account. This
endpoint invalidates all access tokens for the user, including the token used in
the request, and therefore the attacker is unable to take over the account in
this way.
operationId: logout_all
security:
- accessToken: []
responses:
200:
description: The user's access tokens were succesfully invalidated.
description: The user's access tokens were successfully invalidated.
schema:
type: object
properties: {}

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,41 @@ 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:
$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"
}
]
}

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

@ -49,7 +49,7 @@ paths:
name: limit
description: Limit on the number of events to return in this request.
required: false
x-example: "20"
x-example: 20
- in: query
name: only
type: string
@ -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"

25
api/client-server/openid.yaml
View file

@ -62,7 +62,7 @@ paths:
200:
description: |-
OpenID token information. This response is nearly compatible with the
response documented in the `OpenID 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
response documented in the `OpenID Connect 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
with the only difference being the lack of an ``id_token``. Instead,
the Matrix homeserver's name is provided.
examples:
@ -73,28 +73,7 @@ paths:
"expires_in": 3600,
}
schema:
type: object
properties:
access_token:
type: string
description: |-
An access token the consumer may use to verify the identity of
the person who generated the token. This is given to the federation
API ``GET /openid/userinfo``.
token_type:
type: string
description: The string ``Bearer``.
matrix_server_name:
type: string
description: |-
The homeserver domain the consumer should use when attempting to
verify the user's identity.
expires_in:
type: integer
description: |-
The number of seconds before this token expires and a new one must
be generated.
required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
$ref: "definitions/openid_token.yaml"
429:
description: This request was rate-limited.
schema:

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"
}
]
}

2
api/client-server/presence.yaml
View file

@ -62,7 +62,7 @@ paths:
description: The new presence state.
status_msg:
type: string
description: "The status message to attach to this state."
description: The status message to attach to this state.
required: ["presence"]
responses:
200:

4
api/client-server/profile.yaml
View file

@ -45,7 +45,7 @@ paths:
x-example: "@alice:example.com"
- in: body
name: displayName
description: The display name info.
description: The new display name information.
required: true
schema:
type: object
@ -119,7 +119,7 @@ paths:
x-example: "@alice:example.com"
- in: body
name: avatar_url
description: The avatar url info.
description: The new avatar information.
required: true
schema:
type: object

39
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,
@ -407,9 +412,9 @@ paths:
description: |-
The action(s) to perform when the conditions for this rule are met.
items:
type: string
enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
type:
- string
- object
conditions:
type: array
description: |-
@ -493,6 +498,8 @@ paths:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
tags:
- Push notifications
put:
summary: "Enable or disable a push rule."
description: |-
@ -585,7 +592,10 @@ paths:
description: The actions for this push rule.
examples:
application/json: {
"actions": ["notify"]
"actions": [
"notify",
{"set_tweak": "sound", "value": "bing"}
]
}
schema:
type: object
@ -594,8 +604,12 @@ paths:
type: array
description: The action(s) to perform for this rule.
items:
type: string
type:
- string
- object
required: ["actions"]
tags:
- Push notifications
put:
summary: "Set the actions for a push rule."
description: |-
@ -639,12 +653,15 @@ paths:
type: array
description: The action(s) to perform for this rule.
items:
type: string
enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
type:
- string
- object
required: ["actions"]
example: {
"actions": ["notify"]
"actions": [
"notify",
{"set_tweak": "highlight"}
]
}
responses:
200:

3
api/client-server/redaction.yaml
View file

@ -37,7 +37,7 @@ paths:
This cannot be undone.
Users may redact their own events, and any user with a power level
greater than or equal to the `redact` power level of the room may
greater than or equal to the ``redact`` power level of the room may
redact events there.
operationId: redactEvent
security:
@ -65,6 +65,7 @@ paths:
x-example: "37"
- in: body
name: body
required: true
schema:
type: object
example: {

239
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,9 +81,10 @@ 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
required: true
schema:
type: object
properties:
@ -84,16 +94,9 @@ paths:
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.
"$ref": "definitions/auth_data.yaml"
bind_email:
type: boolean
description: |-
If true, the server binds the email used for authentication to
the Matrix ID with the identity server.
example: false
authenticate the ``register`` call itself.
allOf:
- "$ref": "definitions/auth_data.yaml"
username:
type: string
description: |-
@ -142,7 +145,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 +197,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 +219,25 @@ 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
should validate the email itself, either by sending a validation email
itself or by using a service it has control over.
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 +269,25 @@ 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
should validate the phone number itself, either by sending a validation
message itself or by using a service it has control over.
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,19 +321,24 @@ 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. Whether other access tokens for
the user are revoked depends on the request parameters.
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
@ -346,10 +346,20 @@ paths:
type: string
description: The new password for the account.
example: "ihatebananas"
logout_devices:
type: boolean
description: |-
Whether the user's other access tokens, and their associated devices, should be
revoked if the request succeeds. Defaults to true.
When ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_
for the user's remaining devices.
example: true
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
Additional authentication information for the user-interactive authentication API.
allOf:
- "$ref": "definitions/auth_data.yaml"
required: ["new_password"]
responses:
200:
@ -373,16 +383,21 @@ 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 should validate the email itself, either by sending a
validation email itself or by using a service it has control over.
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
@ -393,22 +408,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
@ -423,7 +428,9 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
@ -435,16 +442,20 @@ 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 should validate the phone number itself, either by sending a
validation message itself or by using a service it has control over.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
@ -455,22 +466,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: "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
@ -485,7 +486,9 @@ paths:
400:
description: |-
The referenced third party identifier is not recognised by the
homeserver, or the request was invalid
homeserver, or the request was invalid. The error code ``M_SERVER_NOT_TRUSTED``
can be returned if the server does not trust/support the identity server
provided in the request.
schema:
$ref: "definitions/errors/error.yaml"
examples:
@ -507,26 +510,58 @@ paths:
The homeserver may change the flows available depending on whether a
valid access token is provided.
Unlike other endpoints, this endpoint does not take an ``id_access_token``
parameter because the homeserver is expected to sign the request to the
identity server instead.
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body
required: true
schema:
type: object
properties:
auth:
description: |-
Additional authentication information for the user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
allOf:
- $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",

2
api/client-server/room_send.yaml
View file

@ -85,5 +85,7 @@ paths:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
tags:
- Room participation

88
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.
@ -42,6 +45,12 @@ 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.
If the event type being sent is ``m.room.canonical_alias`` servers
SHOULD ensure that any new aliases being listed in the event are valid
per their grammar/syntax and that they point to the room ID where the
state event is to be sent. Servers do not validate aliases which are
being removed or are already present in the state event.
operationId: setRoomStateWithKey
security:
- accessToken: []
@ -61,7 +70,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 +81,7 @@ paths:
type: object
example: {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
"displayname": "Alice Margatroid"
}
responses:
@ -87,6 +98,8 @@ paths:
type: string
description: |-
A unique identifier for the event.
required:
- event_id
403:
description: |-
The sender doesn't have permission to send the event into the room.
@ -97,70 +110,23 @@ paths:
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
}
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:
400:
description: |-
The sender doesn't have permission to send the event into the room.
The sender's request is malformed.
Some example error codes include:
* ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``
event have invalid syntax.
* ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event
do not point to the room ID for which the state event is to be sent to.
schema:
$ref: "definitions/errors/error.yaml"
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have permission to send the event."
"errcode": "M_BAD_ALIAS",
"error": "The alias '#hello:example.org' does not point to this room."
}
tags:
- Room participation

3
api/client-server/room_upgrades.yaml
View file

@ -45,7 +45,6 @@ paths:
- in: body
name: body
required: true
description: The request body
schema:
type: object
properties:
@ -90,4 +89,4 @@ paths:
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room ugprades
- Room upgrades

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"
}
]
}

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

@ -45,6 +45,7 @@ paths:
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
required: true
schema:
type: object
example: {
@ -95,7 +96,8 @@ paths:
# for now :/
description: |-
This takes a `filter`_.
$ref: "definitions/room_event_filter.yaml"
allOf:
- $ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string
@ -280,7 +282,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 +349,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"
}
}
]

149
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
@ -120,11 +136,56 @@ paths:
title: Joined Rooms
type: object
description: |-
The rooms that the user has joined.
The rooms that the user has joined, mapped as room ID to
room information.
additionalProperties:
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 +228,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
@ -187,7 +250,8 @@ paths:
title: Invited Rooms
type: object
description: |-
The rooms that the user has been invited to.
The rooms that the user has been invited to, mapped as room ID to
room information.
additionalProperties:
title: Invited Room
type: object
@ -212,36 +276,14 @@ 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
type: object
description: |-
The rooms that the user has left or been banned from.
The rooms that the user has left or been banned from, mapped as room ID to
room information.
additionalProperties:
title: Left Room
type: object
@ -310,11 +352,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 +368,28 @@ 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"
"$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"
"$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"
"$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": {

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

@ -92,6 +92,7 @@ paths:
type: object
example: {
"id_server": "matrix.org",
"id_access_token": "abc123_OpaqueString",
"medium": "email",
"address": "cheeky@monkey.com"
}
@ -99,6 +100,12 @@ paths:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
id_access_token:
type: string
description: |-
An access token previously registered with the identity server. Servers
can treat this as optional to distinguish between r0.5-compatible clients
and this specification version.
medium:
type: string
# TODO: Link to Identity Service spec when it eixsts
@ -106,7 +113,7 @@ paths:
address:
type: string
description: The invitee's third party identifier.
required: ["id_server", "medium", "address"]
required: ["id_server", "id_access_token", "medium", "address"]
responses:
200:
description: The user has been invited to join the room.

2
api/client-server/users.yaml
View file

@ -31,7 +31,7 @@ paths:
post:
summary: Searches the user directory.
description: |-
Performs a search for users on the homeserver. The homeserver may
Performs a search for users. The homeserver may
determine which subset of users are searched, however the homeserver
MUST at a minimum consider the users the requesting user shares a
room with and those who reside in public rooms (known to the homeserver).

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

@ -39,7 +39,6 @@ paths:
200:
description: Server discovery information.
schema:
type: object
"$ref": "definitions/wellknown/full.yaml"
404:
description: No server discovery information available.

101
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
@ -90,7 +91,7 @@ paths:
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/bind":
"/3pid/bind":
post:
summary: Publish an association between a session and a Matrix user ID.
description: |-
@ -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"]

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

@ -30,8 +30,8 @@ properties:
country:
type: string
description: |-
The two-letter uppercase ISO country code that the number in
``phone_number`` should be parsed as if it were dialled from.
The two-letter uppercase ISO-3166-1 alpha-2 country code that the
number in ``phone_number`` should be parsed as if it were dialled from.
example: "GB"
phone_number:
type: string
@ -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

5
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
@ -162,7 +165,7 @@ paths:
description: The token generated by the ``requestToken`` call and emailed to the user.
x-example: atoken
responses:
"200":
200:
description: Email address is validated.
"3xx":
description: |-

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

4
api/identity/lookup.yaml
View file

@ -16,7 +16,7 @@
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Lookup API"
title: "Matrix Identity Service Lookup API"
version: "1.0.0"
host: localhost:8090
schemes:
@ -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

5
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
@ -164,7 +167,7 @@ paths:
description: The token generated by the ``requestToken`` call and sent to the user.
x-example: atoken
responses:
"200":
200:
description: Phone number is validated.
"3xx":
description: |-

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:

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

@ -0,0 +1,333 @@
# 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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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).
Another common error code is ``M_TERMS_NOT_SIGNED`` where the user
needs to `agree to more terms`_ in order to continue.
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.

131
api/identity/v2_auth.yaml Normal file
View file

@ -0,0 +1,131 @@
# 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 Authentication 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:
"/account/register":
post:
summary: Exchanges an OpenID token for an access token.
description: |-
Exchanges an OpenID token from the homeserver for an access token to
access the identity server. The request body is the same as the values
returned by ``/openid/request_token`` in the Client-Server API.
operationId: registerAccount
parameters:
- in: body
name: body
schema:
$ref: "../client-server/definitions/openid_token.yaml"
responses:
200:
description: |-
A token which can be used to authenticate future requests to the
identity server.
examples:
application/json: {
"token": "abc123_OpaqueString"
}
schema:
type: object
properties:
token:
type: string
description: |-
An opaque string representing the token to authenticate future
requests to the identity server with.
required: ['token']
"/account":
get:
summary: Gets account holder information for a given token.
description: |-
Gets information about what user owns the access token used in the request.
operationId: getAccount
security:
- accessToken: []
parameters: []
responses:
200:
description: The token holder's information.
examples:
application/json: {
"user_id": "@alice:example.org"
}
schema:
type: object
properties:
user_id:
type: string
description: The user ID which registered the token.
required: ['user_id']
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
"/account/logout":
post:
summary: Logs out an access token, rendering it unusable.
description: |-
Logs out the access token, preventing it from being used to authenticate
future requests to the server.
operationId: logout
security:
- accessToken: []
parameters: []
responses:
200:
description: The token was successfully logged out.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The token is not registered or is otherwise unknown to the server.
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

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

@ -0,0 +1,216 @@
# 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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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']
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
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.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

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

@ -0,0 +1,112 @@
# 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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

148
api/identity/v2_lookup.yaml Normal file
View file

@ -0,0 +1,148 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# 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 Lookup 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:
"/hash_details":
get:
summary: Gets hash function information from the server.
description: |-
Gets parameters for hashing identifiers from the server. This can include
any of the algorithms defined in this specification.
operationId: getHashDetails
security:
- accessToken: []
parameters: []
responses:
200:
description: The hash function information.
examples:
application/json: {
"lookup_pepper": "matrixrocks",
"algorithms": ["none", "sha256"]
}
schema:
type: object
properties:
lookup_pepper:
type: string
description: |-
The pepper the client MUST use in hashing identifiers, and MUST
supply to the ``/lookup`` endpoint when performing lookups.
Servers SHOULD rotate this string often.
algorithms:
type: array
items:
type: string
description: |-
The algorithms the server supports. Must contain at least ``sha256``.
required: ['lookup_pepper', 'algorithms']
"/lookup":
post:
summary: Look up Matrix User IDs for a set of 3PIDs.
description: |-
Looks up the set of Matrix User IDs which have bound the 3PIDs given, if
bindings are available. Note that the format of the addresses is defined
later in this specification.
operationId: lookupUsersV2
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
algorithm:
type: string
description: |-
The algorithm the client is using to encode the ``addresses``. This
should be one of the available options from ``/hash_details``.
example: "sha256"
pepper:
type: string
description: |-
The pepper from ``/hash_details``. This is required even when the
``algorithm`` does not make use of it.
example: "matrixrocks"
addresses:
type: array
items:
type: string
description: |-
The addresses to look up. The format of the entries here depend on
the ``algorithm`` used. Note that queries which have been incorrectly
hashed or formatted will lead to no matches.
example: [
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc",
"nlo35_T5fzSGZzJApqu8lgIudJvmOQtDaHtr-I4rU7I"
]
required: ['algorithm', 'pepper', 'addresses']
responses:
200:
description:
The associations for any matched ``addresses``.
examples:
application/json: {
"mappings": {
"4kenr7N9drpCJ4AfalmlGQVsOn3o2RHjkADUpXJWZUc": "@alice:example.org"
}
}
schema:
type: object
properties:
mappings:
type: object
description: |-
Any applicable mappings of ``addresses`` to Matrix User IDs. Addresses
which do not have associations will not be included, which can make
this property be an empty object.
title: AssociatedMappings
additionalProperties:
type: string
required: ['mappings']
400:
description:
The client's request was invalid in some way. One possible problem could
be the ``pepper`` being invalid after the server has rotated it - this is
presented with the ``M_INVALID_PEPPER`` error code. Clients SHOULD make
a call to ``/hash_details`` to get a new pepper in this scenario, being
careful to avoid retry loops.
``M_INVALID_PARAM`` can also be returned to indicate the client supplied
an ``algorithm`` that is unknown to the server.
examples:
application/json: {
"errcode": "M_INVALID_PEPPER",
"error": "Unknown or invalid pepper - has it been rotated?"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

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

@ -0,0 +1,218 @@
# 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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
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']
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"
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.
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

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']

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

@ -0,0 +1,176 @@
# 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"
403:
description: |
The user must do something in order to use this endpoint. One example
is an ``M_TERMS_NOT_SIGNED`` error where the user must `agree to more terms`_.
examples:
application/json: {
"errcode": "M_TERMS_NOT_SIGNED",
"error": "Please accept our updated terms of service before continuing"
}
schema:
$ref: "../client-server/definitions/errors/error.yaml"

149
api/identity/v2_terms.yaml Normal file
View file

@ -0,0 +1,149 @@
# 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 Terms of Service 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:
"/terms":
get:
summary: Gets the terms of service offered by the server.
description: |-
Gets all the terms of service offered by the server. The client is expected
to filter through the terms to determine which terms need acceptance from the
user. Note that this endpoint does not require authentication.
operationId: getTerms
parameters: []
responses:
200:
description: |-
The terms of service offered by the server.
examples:
application/json: {
"policies": {
"terms_of_service": {
"version": "2.0",
"en": {
"name": "Terms of Service",
"url": "https://example.org/somewhere/terms-2.0-en.html"
},
"fr": {
"name": "Conditions d'utilisation",
"url": "https://example.org/somewhere/terms-2.0-fr.html"
}
},
"privacy_policy": {
"version": "1.2",
"en": {
"name": "Privacy Policy",
"url": "https://example.org/somewhere/privacy-1.2-en.html"
},
"fr": {
"name": "Politique de confidentialité",
"url": "https://example.org/somewhere/privacy-1.2-fr.html"
}
}
}
}
schema:
type: object
properties:
policies:
type: object
title: Policy Map
description: |-
The policies the server offers. Mapped from arbitrary ID (unused in
this version of the specification) to a Policy Object.
additionalProperties:
type: object
title: Policy Object
description: |-
The policy. Includes a map of language (ISO 639-2) to language-specific
policy information.
properties:
version:
type: string
description: |-
The version for the policy. There are no requirements on what this
might be and could be "alpha", semantically versioned, or arbitrary.
required: ['version']
# TODO: TravisR - Make this render
additionalProperties:
type: object
title: Internationalised Policy
description: |-
The policy information for the specified language.
properties:
name:
type: string
description: The translated name of the policy.
url:
type: string
description: |-
The URL, which should include the policy ID, version, and language
in it, to be presented to the user as the policy. URLs should have
all three criteria to avoid conflicts when the policy is updated
in the future: for example, if this was "https://example.org/terms.html"
then the server would be unable to update it because the client would
have already added that URL to the ``m.accepted_terms`` collection.
required: ['name', 'url']
required: ['policies']
post:
summary: Indicates acceptance of terms to the server.
description: |-
Called by a client to indicate that the user has accepted/agreed to the included
set of URLs. Servers MUST NOT assume that the client will be sending all previously
accepted URLs and should therefore append the provided URLs to what the server
already knows has been accepted.
Clients MUST provide the URL of the policy in the language that was presented
to the user. Servers SHOULD consider acceptance of any one language's URL as
acceptance for all other languages of that policy.
The server should avoid returning ``M_TERMS_NOT_SIGNED`` because the client
may not be accepting all terms at once.
operationId: agreeToTerms
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
user_accepts:
type: array
items:
type: string
description: The URLs the user is accepting in this request.
example: "https://example.org/somewhere/terms-2.0-en.html"
required: ['user_accepts']
responses:
200:
description: |-
The server has considered the user as having accepted the provided URLs.
examples:
application/json: {}
schema:
type: object

21
api/openapi_extensions.md
View file

@ -6,6 +6,19 @@ across the specification. The defined extensions are listed below. Extensions
should not break parsers, however if extra functionality is required, aware
parsers should be able to take advantage of the added syntax.
## Using multiple files to describe API
To ease API design and management, the API definition is split across several
files. Each of these files is self-contained valid OpenAPI (except
client-server files that become valid OpenAPI after substituting
`%CLIENT_MAJOR_VERSION%` with `unstable` or an API release).
There is no single root file in the source tree as OpenAPI requires; this file
can be generated by `dump_swagger.py` (also doing the substitution mentioned
above). The script does not convert the extensions described further in this
document (`oneOf` and parameter exploding) so there can be minor
interoperability issues with tooling that expects compliant Swagger.
## Extensible Query Parameters
<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->
@ -43,3 +56,11 @@ doesn't work, as in the following example:
properties:
...
```
## OpenAPI 3's "2xx" format for response codes
<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
In some cases, the schema will have HTTP response code definitions like
`2xx`, `3xx`, and `4xx`. These indicate that a response code within those
ranges (`2xx` = `200` to `299`) is valid for the schema.

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",

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

@ -32,8 +32,8 @@ paths:
summary: Retrieves the events which precede the given event
description: |-
Retrieves a sliding-window history of previous PDUs that occurred in the given room.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it
are retrieved, up to the total number given by the ``limit``.
Starting from the PDU ID(s) given in the ``v`` argument, the PDUs given in ``v`` and
the PDUs that preceded them are retrieved, up to the total number given by the ``limit``.
operationId: backfillRoom
security:
- signedRequest: []
@ -63,8 +63,16 @@ paths:
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
.. Note::
Though the PDU definitions require that ``prev_events`` and ``auth_events`` be limited
in number, the response of backfill MUST NOT be validated on these specific restrictions.
Due to historical reasons, it is possible that events which were previously accepted
would now be rejected by these limitations. The events should be rejected per usual by
the ``/send``, ``/get_missing_events``, and remaining endpoints.
schema:
$ref: "definitions/transaction.yaml"
$ref: "definitions/unlimited_pdu_transaction.yaml"
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing

2
api/server-server/definitions/invite_event.yaml
View file

@ -12,7 +12,7 @@
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Invite Event
title: InviteEvent
description: |-
An invite event. Note that events have a different format depending on the
room version - check the `room version specification`_ for precise event formats.

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

@ -20,7 +20,6 @@ properties:
server_name:
type: string
description: DNS name of the homeserver.
required: true
example: "example.org"
verify_keys:
type: object
@ -31,7 +30,6 @@ properties:
algorithm and ``abc123`` being the version in the example below). Together,
this forms the Key ID. The version must have characters matching the regular
expression ``[a-zA-Z0-9_]``.
required: true
additionalProperties:
type: object
title: Verify Key
@ -44,8 +42,8 @@ properties:
key:
type: string
description: The `Unpadded Base64`_ encoded key.
required: true
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
required: ["key"]
old_verify_keys:
type: object
description: |-
@ -69,31 +67,35 @@ properties:
type: integer
format: int64
description: POSIX timestamp in milliseconds for when this key expired.
required: true
example: 1532645052628
key:
type: string
description: The `Unpadded Base64`_ encoded key.
required: true
example: "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
required: ["expired_ts", "key"]
signatures:
type: object
description: Digital signatures for this object signed using the ``verify_keys``.
description: |-
Digital signatures for this object signed using the ``verify_keys``.
The signature is calculated using the process described at `Signing
JSON`_.
title: Signatures
additionalProperties:
type: object
title: Signed Server
example: {
"example.org": {
"ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
}
}
additionalProperties:
type: string
name: Encoded Signature Verification Key
valid_until_ts:
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
required: ["server_name", "verify_keys"]

10
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:
@ -28,6 +32,10 @@ allOf:
description: |-
Event IDs for the authorization events that would
allow this event to be in the room.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
example: ["$base64EncodedHash", "$AnotherEvent"]
prev_events:
type: array
@ -37,6 +45,8 @@ allOf:
description: |-
Event IDs for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
example: ["$base64EncodedHash", "$AnotherEvent"]
hashes:
type: object

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

@ -0,0 +1,53 @@
# 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.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
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.
Must contain less than or equal to 20 events.
example: ["$URLsafe-base64EncodedHash", "$Another_Event"]
required:
- auth_events
- prev_events

58
api/server-server/definitions/send_join_response.yaml Normal file
View file

@ -0,0 +1,58 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain for the entire current room state prior to the join event.
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>`_ that make up the auth chain. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "../examples/minimal_pdu.json"
state:
type: array
description: |-
The resolved current room state prior to the join event.
The event format varies depending on the room version - check the `room version specification`_
for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ["auth_chain", "state", "origin"]

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']

8
api/server-server/definitions/unsigned_pdu_base.yaml
View file

@ -53,6 +53,8 @@ properties:
description: |-
Event IDs and reference hashes for the most recent events in the room
that the homeserver was aware of when it made this event.
Must contain less than or equal to 20 events.
items:
type: array
maxItems: 2
@ -84,6 +86,10 @@ properties:
description: |-
Event IDs and reference hashes for the authorization events that would
allow this event to be in the room.
Must contain less than or equal to 10 events. Note that if the relevant
auth event selection rules are used, this restriction should never be
encountered.
items:
type: array
maxItems: 2
@ -109,7 +115,7 @@ properties:
example: "$def456:matrix.org"
unsigned:
type: object
title: Example Unsigned Data
title: UnsignedData
description: |-
Additional data added by the origin server but not covered by the ``signatures``. More
keys than those defined here may be used.

134
api/server-server/event_auth.yaml
View file

@ -72,137 +72,3 @@ paths:
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain']
"/query_auth/{roomId}/{eventId}":
post:
summary: Compare auth chains with the receiving server
description: |-
Compares the auth chain provided with what the receiving server has for the
room ID and event ID combination.
The auth difference can be calculated in two parts, where the "remote auth"
is the auth chain provided by the sending server and the "local auth" is the
auth chain the receiving server has. With those lists, the algorithm works
bottom-up after sorting each chain by depth then by event ID. The differences
are then discovered and returned as the response to this API call.
operationId: compareEventAuth
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to compare the auth chain in.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID to compare the auth chain of.
required: true
x-example: "$helloworld:example.org"
- in: body
name: body
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The auth chain (the "remote auth"). 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 auth chain. 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"
missing:
type: array
description: |-
A list of event IDs that the sender thinks the receiver is missing.
items:
type: string
example: []
rejects:
type: object
description: |-
The set of events that the sending server has rejected from the provided
auth chain.
The ``string`` key is the event ID that was rejected.
additionalProperties:
type: object
title: Rejection Reason
properties:
reason:
type: enum
enum: ['auth_error', 'replaced', 'not_ancestor']
description: |-
The reason for the event being rejected.
required: ['reason']
example: {
"$some_event:example.org": {
"reason": "auth_error"
}
}
required: ['auth_chain']
responses:
200:
description: The auth chain differences, as determined by the receiver.
schema:
type: object
properties:
auth_chain:
type: array
description: |-
The auth chain the receiver has, and used to determine the auth
chain differences (the "local auth"). 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 auth chain. 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"
missing:
type: array
description: |-
The list of event IDs that the receiver believes it is missing,
after comparing the "remote auth" and "local auth" chains.
items:
type: string
example: ["$a_missing_event:example.org"]
rejects:
type: object
description: |-
The set of events that the receiving server has rejected from the
auth chain, not including events that the sending server is missing
as determined from the difference algorithm.
The ``string`` key is the event ID that was rejected.
additionalProperties:
type: object
title: Rejection Reason
properties:
reason:
type: enum
enum: ['auth_error', 'replaced', 'not_ancestor']
description: |-
The reason for the event being rejected.
required: ['reason']
example: {
"$some_event:example.org": {
"reason": "auth_error"
}
}
required: ['auth_chain', 'missing', 'rejects']

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"
}

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

@ -70,7 +70,7 @@ paths:
properties:
unsigned:
type: object
title: Unsigned Event Content
title: UnsignedData
description: |-
Information included alongside the event that is not signed. May include more
than what is listed here.
@ -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"

65
api/server-server/joins.yaml → api/server-server/joins-v1.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
@ -62,7 +63,7 @@ paths:
200:
description: |-
A template to be used for the rest of the `Joining Rooms`_ handshake. Note that
events have a different format depending on the room version - check the
events have a different format depending on the room version - check the
`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.**
@ -161,18 +162,32 @@ paths:
"error": "Your homeserver does not support the features required to join this room",
"room_version": "3"
}
404:
description: |-
The room that the joining server is attempting to join is unknown
to the receiving server.
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Unknown room",
}
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
description: |-
.. Note::
Servers should instead prefer to use the v2 ``/send_join``
endpoint.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoin
operationId: sendJoinV1
security:
- signedRequest: []
parameters:
@ -257,47 +272,7 @@ paths:
- type: integer
description: The value ``200``.
example: 200
- type: object
title: Room State
description: The state for the room.
properties:
origin:
type: string
description: The resident server's DNS name.
auth_chain:
type: array
description: |-
The auth chain. 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>`_ that make up the auth chain. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
state:
type: array
description: |-
The room state. The event format varies depending on the room version -
check the `room version specification`_ for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
required: ["auth_chain", "state", "origin"]
- $ref: "./definitions/send_join_response.yaml"
examples:
application/json: [
200,

136
api/server-server/joins-v2.yaml Normal file
View file

@ -0,0 +1,136 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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 Federation Join Room API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v2
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
# Note: there is no v2 of make_join (yet)
"/send_join/{roomId}/{eventId}":
put:
summary: Submit a signed join event to a resident server
description: |-
.. Note::
This API is nearly identical to the v1 API with the
exception of the response format being fixed.
This endpoint is preferred over the v1 API as it provides
a more standarised response format. Senders which receive
a 400, 404, or other status code which indicates this endpoint
is not available should retry using the v1 API instead.
Submits a signed join event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoinV2
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID that is about to be joined.
required: true
x-example: "!abc123:matrix.org"
- in: path
name: eventId
type: string
description: The event ID for the join event.
required: true
x-example: "$abc123:example.org"
- in: body
name: body
type: object
required: true
schema:
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value ``join``.
example: "join"
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
example: {
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join"
}
}
responses:
200:
description: |-
The full state for the room, having accepted the join event.
schema:
$ref: "./definitions/send_join_response.yaml"
examples:
application/json: {
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}]
}

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

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

@ -34,7 +34,7 @@ paths:
Intermediate notary servers should cache a response for half of its
lifetime to avoid serving a stale response. Originating servers should
avoid returning responses that expire in less than an hour to avoid
repeated reqests for a certificate that is about to expire. Requesting
repeated requests for a certificate that is about to expire. Requesting
servers should limit how frequently they query for certificates to
avoid flooding a server with requests.
@ -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

14
api/server-server/leaving.yaml → api/server-server/leaving-v1.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2018 New Vector Ltd
# Copyright 2020 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.
@ -53,11 +54,10 @@ paths:
200:
description: |-
A template to be used to call ``/send_leave``. Note that
events have a different format depending on the room version - check the
events have a different format depending on the room version - check the
`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:
@ -143,14 +143,18 @@ paths:
put:
summary: Submit a signed leave event to a resident server
description: |-
.. Note::
Servers should instead prefer to use the v2 ``/send_leave``
endpoint.
Submits a signed leave event to the resident server for it
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
**The request and response body here describe the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendLeave
operationId: sendLeaveV1
security:
- signedRequest: []
parameters:

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