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

Merge remote-tracking branch 'matrix-org/master' into mujx/missing-enum-fields

Browse source
This commit is contained in:
Travis Ralston 2018-08-28 14:10:17 -06:00
commit adef7babfa
439 changed files with 13658 additions and 9384 deletions
Download patch file Download diff file Expand all files Collapse all files

124
.circleci/config.yml Normal file
View file

@ -0,0 +1,124 @@
gendoc: &gendoc
name: Generate the docs
command: |
source /env/bin/activate
scripts/gendoc.py
genswagger: &genswagger
name: Generate the swagger
command: |
source /env/bin/activate
scripts/dump-swagger.py
buildswaggerui: &buildswaggerui
name: Build Swagger UI
command: |
ls scripts/
mkdir -p api/client-server
git clone https://github.com/matrix-org/swagger-ui swagger-ui
cp -r swagger-ui/dist/* api/client-server/
mkdir -p api/client-server/json
cp scripts/swagger/api-docs.json api/client-server/json/
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/content/swagger.css -O api/client-server/swagger.css
wget https://raw.githubusercontent.com/matrix-org/matrix.org/master/scripts/swagger-ui.patch
patch api/client-server/index.html swagger-ui.patch
checkexamples: &checkexamples
name: Check Event Examples
command: |
source /env/bin/activate
cd event-schemas
./check_examples.py
cd ../api
./check_examples.py
genmatrixassets: &genmatrixassets
name: Generate/Verify matrix.org assets
command: |
source /env/bin/activate
./scripts/generate-matrix-org-assets
validateapi: &validateapi
name: Validate OpenAPI specifications
command: |
cd api
npm install
node validator.js -s "client-server"
buildspeculator: &buildspeculator
name: Build Speculator
command: |
cd scripts/speculator
go build -v
buildcontinuserv: &buildcontinuserv
name: Build Continuserv
command: |
cd scripts/continuserv
go build -v
version: 2
jobs:
validate-docs:
docker:
- image: node:alpine
steps:
- checkout
- run: *validateapi
check-docs:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *checkexamples
- run: *genmatrixassets # We don't actually use the assets, but we do want to make sure they build
build-docs:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *gendoc
- store_artifacts:
path: scripts/gen
- run:
name: "Doc build is available at:"
command: DOCS_URL="${CIRCLE_BUILD_URL}/artifacts/${CIRCLE_NODE_INDEX}/${CIRCLE_WORKING_DIRECTORY/#\~/$HOME}/scripts/gen/index.html"; echo $DOCS_URL
build-swagger:
docker:
- image: uhoreg/matrix-doc-build
steps:
- checkout
- run: *genswagger
- run: *buildswaggerui
- store_artifacts:
path: api/client-server/
- run:
name: "Swagger UI is available at:"
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
steps:
- checkout
- run:
name: Install Dependencies
command: |
go get -v github.com/hashicorp/golang-lru
go get -v gopkg.in/fsnotify/fsnotify.v1
- run: *buildcontinuserv
- run: *buildspeculator
workflows:
version: 2
build-spec:
jobs:
- build-docs
- build-swagger
- check-docs
- validate-docs
- build-dev-scripts
notify:
webhooks:
- url: https://giles.cadair.com/circleci

17
.gitignore vendored
View file

@ -1,10 +1,13 @@
scripts/gen
scripts/continuserv/continuserv
scripts/speculator/speculator
/api/node_modules
/assets
/assets.tar.gz
/env*
/scripts/gen
/scripts/continuserv/continuserv
/scripts/speculator/speculator
/scripts/swagger
templating/out
/scripts/tmp
/templating/out
*.pyc
*.swp
supporting-docs/_site
supporting-docs/.sass-cache
api/node_modules
_rendered.rst

150
CONTRIBUTING.rst
View file

@ -1,55 +1,35 @@
Contributing to matrix-doc
==========================
Everyone is welcome to contribute to the ``matrix-doc`` project, provided that they
are willing to license their contributions under the same license as the
project itself. We follow a simple 'inbound=outbound' model for contributions:
the act of submitting an 'inbound' contribution means that the contributor
agrees to license the code under the same terms as the project's overall
'outbound' license - in our case, this is Apache Software License
v2 (see LICENSE).
Everyone is welcome to contribute to the Matrix specification!
Please ensure that you sign off your contributions. See `Sign off`_ below.
Code style
----------
The documentation style is described at
https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
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.
Matrix-doc workflows
--------------------
Specification changes
~~~~~~~~~~~~~~~~~~~~~
The Matrix specification documents the APIs which Matrix clients can use. 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.
The Matrix specification documents the APIs which Matrix clients and servers use.
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 following
workflow:
1. Create a discussion document outlining the proposed change. The document
should include details such as the HTTP endpoint being changed (or the
suggested URL for a new endpoint), any new or changed parameters and response
fields, and generally as much detail about edge-cases and error handling as
is practical at this stage.
The Matrix Core Team's preferred tool for such discussion documents is
`Google Docs <https://docs.google.com>`_ thanks to its support for comment
threads. Works in progress are kept in a folder at
https://drive.google.com/drive/folders/0B4wHq8qP86r2ck15MHEwMmlNVUk.
2. Seek feedback on the proposal. `#matrix-dev:matrix.org
<http://matrix.to/#/#matrix-dev:matrix.org>`_ is a good place to reach the
core team and others who may be interested in your proposal.
3. Implement the changes in servers and clients. Refer to the CONTRIBUTING files
of the relevant projects for details of how best to do this.
In general we will be unable to publish specification updates until the
reference server implements them, and they have been proven by a working
client implementation.
4. Iterate steps 1-3 as necessary.
5. Write the specification for the change, and create a `pull request`_ for
it. It may be that much of the text of the change can be taken directly from
the discussion document, though typically some effort will be needed to
change to the ReST syntax and to ensure that the text is as clear as
possible.
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*.
Other changes
@ -59,43 +39,81 @@ The above process is unnecessary for smaller changes, and those which do not
put new requirements on servers. This category of changes includes the
following:
* changes to supporting documentation
* Changes to the scripts used to generate the specification.
* changes to the scripts used to generate the specification
* Addition of features which have been in use in practice for some time, but
have never made it into the spec (including anything with the `spec-omission
<https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_ label).
* clarifications to the specification which do not change the behaviour of
* Likewise, corrections to the specification, to fix situations where, in
practice, servers and clients behave differently to the specification,
including anything with the `spec-bug
<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>`_.)
* Clarifications to the specification which do not change the behaviour of
Matrix servers or clients in a way which might introduce compatibility
problems for existing deployments. 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.
problems for existing deployments. This includes anything with the
`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 such changes, please do just open a `pull request`_.
.. _pull request: https://help.github.com/articles/about-pull-requests
Pull requests
~~~~~~~~~~~~~
.. _pull request: `Pull requests`_
The preferred and easiest way to contribute changes to the ``matrix-doc`` project
is to fork it on github, and then create a pull request to ask us to pull your
changes into our repo (https://help.github.com/articles/using-pull-requests/).
Adding to the changelog
~~~~~~~~~~~~~~~~~~~~~~~
(Note that, unlike most of the other matrix.org projects, pull requests for
matrix-doc should be based on the ``master`` branch.)
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.
Code style
~~~~~~~~~~
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
under ``changelogs/client_server/newsfragments``.
The documentation style is described at
https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
To create a changelog entry, create a file named in the format ``prNumber.type`` in
the ``newsfragments`` directory. The ``type`` can be one of the following:
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.
* ``new`` - Used when adding new endpoints. Please have the file contents be the
method and route being added, surrounded in RST code tags. For example: ``POST
/accounts/whoami``
* ``feature`` - Used when adding backwards-compatible changes to the API.
* ``clarification`` - Used when an area of the spec is being improved upon and does
not change or introduce any functionality.
* ``breaking`` - Used when the change is not backwards compatible.
* ``deprecation`` - Used when deprecating something
All news fragments must have a brief summary explaining the change in the contents
of the file.
Changes that do not change the spec, such as changes to the build script, formatting,
CSS, etc should not get a news fragment.
Sign off
~~~~~~~~
--------
We ask that everybody who contributes to their project signs off their
contributions, as explained below.
We follow a simple 'inbound=outbound' model for contributions: the act of
submitting an 'inbound' contribution means that the contributor agrees to
license their contribution under the same terms as the project's overall 'outbound'
license - in our case, this is Apache Software License v2 (see LICENSE).
In order to have a concrete record that your contribution is intentional
and you agree to license it under the same terms as the project's license, we've adopted the

154
README.rst
View file

@ -1,39 +1,141 @@
This repository contains the documentation for Matrix.
This repository contains the Matrix specification.
Structure
=========
If you want to ask more about the specification, join us on
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
- ``api`` : Contains the HTTP API specification.
- ``attic``: Contains historical sections of specification for reference
We welcome contributions to the spec! See the notes below on `Building the
specification`_, and `<CONTRIBUTING.rst>`_ to get started making contributions.
Note that the Matrix Project lists, which were previously kept in this
repository, are now in https://github.com/matrix-org/matrix.org.
Structure of this repository
============================
- ``api`` : `OpenAPI`_ (swagger) specifications for the the HTTP APIs.
- ``attic``: historical sections of specification for reference
purposes.
- ``changelogs``: Contains change logs for the various parts of the
- ``changelogs``: change logs for the various parts of the
specification.
- ``drafts``: Previously, contained documents which were under discussion for
future incusion into the specification and/or supporting documentation. This
is now historical, as we use separate discussion documents (see
`<CONTRIBUTING.rst>`_).
- ``event-schemas``: Contains the `JSON Schema`_ for all Matrix events
- ``event-schemas``: the `JSON Schema`_ for all Matrix events
contained in the specification, along with example JSON files.
- ``meta``: Contains documents outlining the processes involved when writing
- ``meta``: documents outlining the processes involved when writing
documents, e.g. documentation style, guidelines.
- ``scripts``: Contains scripts to generate formatted versions of the
- ``scripts``: scripts to generate formatted versions of the
documentation, typically HTML.
- ``specification``: Contains the specification split up into sections.
- ``supporting-docs``: Contains additional documents which explain design
decisions, examples, use cases, etc.
- ``templating``: Contains the templates and templating system used to
generate the spec.
Contributing
============
Known issues with the specification are represented as JIRA issues at
`<https://matrix.org/jira/browse/SPEC>`_.
If you want to ask more about the specification, join us on
`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
If you would like to contribute to the specification or supporting
documentation, see `<CONTRIBUTING.rst>`_.
- ``specification``: the specification split up into sections.
.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
.. _JSON Schema: http://json-schema.org/
Building the specification
==========================
The Matrix Spec is generated by a set of scripts, from the RST documents, API
specs and event schemas in this repository.
Preparation
-----------
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
invoked with ``nix-shell scripts/contrib/shell.nix``.)
.. TODO: Possibly we need some libs installed; should record what they are.
.. _`Nix`: https://nixos.org/nix/
Generating the specification
----------------------------
To rebuild the specification, use ``scripts/gendoc.py``::
source env/bin/activate
./scripts/gendoc.py
The above will write the rendered version of the specification to
``scripts/gen``. To view it, point your browser at ``scripts/gen/index.html``.
Windows users
~~~~~~~~~~~~~
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
cloned matrix-doc directory and run the following::
cd api\client-server\definitions
del event-schemas
mklink /D event-schemas "..\..\..\event-schemas"
This will delete the file and replace it with a symlink. Git should not detect
this as a change, and you should be able to go back to building the project.
Generating the OpenAPI (Swagger) specs
--------------------------------------
`Swagger`_ is a framework for representing RESTful APIs. We use it to generate
interactive documentation for our APIs.
Before the Swagger docs can be used in the Swagger UI (or other tool expecting
a Swagger specs, they must be combined into a single json file. This can be
done as follows::
source env/bin/activate
./scripts/dump-swagger.py
By default, ``dump-swagger`` will write to ``scripts/swagger/api-docs.json``.
To make use of the generated file, there are a number of options:
* It can be uploaded from your filesystem to an online editor/viewer such as
http://editor.swagger.io/
* You can run a local HTTP server by running
``./scripts/swagger-http-server.py``, and then view the documentation via an
online viewer; for example, at
http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json
* You can host the swagger UI yourself. See
https://github.com/swagger-api/swagger-ui#how-to-run for advice on how to do
so.
.. _`Swagger`: http://swagger.io/
Continuserv
-----------
Continuserv is a script which will rebuild the specification every time a file
is changed, and will serve it to a browser over HTTP. It is intended for use by
specification authors, so that they can quickly see the effects of their
changes.
It is written in Go, so you will need the ``go`` compiler installed on your
computer. You will also need to install fsnotify by running::
go get gopkg.in/fsnotify/fsnotify.v1
Then, create a virtualenv as described above under `Preparation`_,
and::
source env/bin/activate
go run ./scripts/continuserv/main.go
You will then be able to view the generated spec by visiting
http://localhost:8000/index.html.
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.

3
api/README
View file

@ -1,3 +1,2 @@
This directory contains swagger-compatible representations of our APIs. See
scripts/README.md for details on how to make use of them.
the main README.rst for details on how to make use of them.

213
api/application-service/application_service.yaml
View file

@ -1,213 +0,0 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
consumes:
- application/json
produces:
- application/json
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the HS when the HS wants to push an event (or
batch of events) to the AS.
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events
schema:
type: object
example: |-
{
"events": [
{
"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",
"user_id": "@bob:localhost"
},
{
"age": 1984,
"content": {
"body": "another incoming message",
"msgtype": "m.text"
},
"event_id": "$1228055551ffsef:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"type": "m.room.message",
"user_id": "@bob:localhost"
}
]
}
description: "Transaction informations"
properties:
events:
type: array
description: A list of events
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: |-
{}
schema:
type: object
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given room alias. The homeserver will only query room
aliases inside the application service's ``aliases`` namespace. The
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
responses:
200:
description: |-
The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set
before responding.
examples:
application/json: |-
{}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given user ID. The homeserver will only query user IDs
inside the application service's ``users`` namespace. The homeserver will
send this request when it receives an event for an unknown user ID in
the application service's namespace.
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
responses:
200:
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
examples:
application/json: |-
{}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
type: object
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: |-
{
"errcode": "M_FORBIDDEN"
}
schema:
type: object
404:
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: |-
{
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
type: object

32
api/application-service/definitions/location.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
properties:
alias:
description: An alias for a matrix room.
type: string
example: "#freenode_#matrix:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: "irc"
fields:
description: Information used to identify this third party location.
type: object
example: {
"network": "freenode",
"channel": "#matrix"
}
required: ['alias', 'protocol', 'fields']
title: Location
type: object

17
api/application-service/definitions/location_batch.yaml Normal file
View file

@ -0,0 +1,17 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party locations.
items:
$ref: location.yaml

113
api/application-service/definitions/protocol.yaml Normal file
View file

@ -0,0 +1,113 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: Protocol
type: object
properties:
user_fields:
description: |-
Fields which may be used to identify a third party user. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the nickname of a user.
type: array
items:
type: string
description: Field used to identify a third party user.
example: ["network", "nickname"]
location_fields:
description: |-
Fields which may be used to identify a third party location. These should be
ordered to suggest the way that entities may be grouped, where higher
groupings are ordered first. For example, the name of a network should be
searched before the name of a channel.
type: array
items:
type: string
description: Field used to identify a third party location.
example: ["network", "channel"]
icon:
description: A content URI representing an icon for the third party protocol.
type: string
example: "mxc://example.org/aBcDeFgH"
field_types:
title: Field Types
description: |-
The type definitions for the fields defined in the ``user_fields`` and
``location_fields``. Each entry in those arrays MUST have an entry here. The
``string`` key for this object is field name itself.
May be an empty object if no fields are defined.
type: object
additionalProperties:
title: Field Type
description: Definition of valid values for a field.
type: object
properties:
regexp:
description: |-
A regular expression for validation of a field's value. This may be relatively
coarse to verify the value as the application service providing this protocol
may apply additional validation or filtering.
type: string
placeholder:
description: An placeholder serving as a valid example of the field value.
type: string
required: ['regexp', 'placeholder']
required: ['fieldname']
example: {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s#]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
}
instances:
description: |-
A list of objects representing independent instances of configuration.
For example, multiple networks on IRC if multiple are provided by the
same application service.
type: array
items:
type: object
title: Protocol Instance
properties:
desc:
type: string
description: A human-readable description for the protocol, such as the name.
example: "Freenode"
icon:
type: string
description: |-
An optional content URI representing the protocol. Overrides the one provided
at the higher level Protocol object.
example: "mxc://example.org/JkLmNoPq"
fields:
type: object
description: Preset values for ``fields`` the client may use to search by.
example: {
"network": "freenode"
}
network_id:
type: string
description: A unique identifier across all instances.
example: "freenode"
required: ['desc', 'fields', 'network_id']
required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

70
api/application-service/definitions/protocol_metadata.yaml Normal file
View file

@ -0,0 +1,70 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: Dictionary of supported third party protocols.
additionalProperties:
$ref: protocol.yaml
example: {
"irc": {
"user_fields": ["network", "nickname"],
"location_fields": ["network", "channel"],
"icon": "mxc://example.org/aBcDeFgH",
"field_types": {
"network": {
"regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
"placeholder": "irc.example.org"
},
"nickname": {
"regexp": "[^\\s]+",
"placeholder": "username"
},
"channel": {
"regexp": "#[^\\s]+",
"placeholder": "#foobar"
}
},
"instances": [
{
"network_id": "freenode",
"desc": "Freenode",
"icon": "mxc://example.org/JkLmNoPq",
"fields": {
"network": "freenode.net",
}
}
]
},
"gitter": {
"user_fields": ["username"],
"location_fields": ["room"],
"field_types": {
"username": {
"regexp": "@[^\\s]+",
"placeholder": "@username"
},
"room": {
"regexp": "[^\\s]+\\/[^\\s]+",
"placeholder": "matrix-org/matrix-doc"
}
},
"instances": [
{
"network_id": "gitter",
"desc": "Gitter",
"icon": "mxc://example.org/zXyWvUt",
"fields": {}
}
]
}
}

33
api/application-service/definitions/user.yaml Normal file
View file

@ -0,0 +1,33 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# TODO: Change userid to user_id as a breaking change
properties:
userid:
description: A Matrix User ID represting a third party user.
type: string
example: "@_gitter_jim:matrix.org"
protocol:
description: The protocol ID that the third party location is a part of.
type: string
example: "gitter"
fields:
description: Information used to identify this third party location.
type: object
example: {
"user": "jim"
}
required: ['userid', 'protocol', 'fields']
title: User
type: object

17
api/application-service/definitions/user_batch.yaml Normal file
View file

@ -0,0 +1,17 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: array
description: List of matched third party users.
items:
$ref: user.yaml

267
api/application-service/protocols.yaml Normal file
View file

@ -0,0 +1,267 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
consumes:
- application/json
produces:
- application/json
paths:
"/_matrix/app/unstable/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the application service supports.
description: |-
This API is called by the homeserver when it wants to present clients
with specific information about the various third party networks that
an application service supports.
operationId: getProtocolMetadata
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
schema:
$ref: definitions/protocol_metadata.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No protocol was found with the given path.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
This API is called by the homeserver in order to retrieve a Matrix
User ID linked to a user on the third party network, given a set of
user parameters.
operationId: queryUserByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No users were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portal rooms leading to a third party location.
description: |-
Retrieve a list of Matrix portal rooms that lead to the matched third party location.
operationId: queryLocationByProtocol
parameters:
- in: path
name: protocol
type: string
description: The protocol ID.
required: true
x-example: irc
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the application
service to help identify the third party location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
responses:
200:
description: |-
All found third party locations.
schema:
$ref: definitions/location_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
"/_matrix/app/unstable/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
responses:
200:
description: |-
An array of third party users.
schema:
$ref: definitions/user_batch.yaml
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: No mappings were found with the given parameters.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

86
api/application-service/query_room.yaml Normal file
View file

@ -0,0 +1,86 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
consumes:
- application/json
produces:
- application/json
paths:
"/rooms/{roomAlias}":
get:
summary: Query if a room alias should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given room alias. The homeserver will only query room
aliases inside the application service's ``aliases`` namespace. The
homeserver will send this request when it receives a request to join a
room alias within the application service's namespace.
operationId: queryRoomByAlias
parameters:
- in: path
name: roomAlias
type: string
description: The room alias being queried.
required: true
x-example: "#magicforest:example.com"
responses:
200:
description: |-
The application service indicates that this room alias exists. The
application service MUST have created a room and associated it with
the queried room alias using the client-server API. Additional
information about the room such as its name and topic can be set
before responding.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this room alias does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

83
api/application-service/query_user.yaml Normal file
View file

@ -0,0 +1,83 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
consumes:
- application/json
produces:
- application/json
paths:
"/users/{userId}":
get:
summary: Query if a user should exist on the application service.
description: |-
This endpoint is invoked by the homeserver on an application service to query
the existence of a given user ID. The homeserver will only query user IDs
inside the application service's ``users`` namespace. The homeserver will
send this request when it receives an event for an unknown user ID in
the application service's namespace, such as a room invite.
operationId: queryUserById
parameters:
- in: path
name: userId
type: string
description: The user ID being queried.
required: true
x-example: "@alice:example.com"
responses:
200:
description: |-
The application service indicates that this user exists. The application
service MUST create the user using the client-server API.
examples:
application/json: {}
schema:
type: object
401:
description: |-
The homeserver has not supplied credentials to the application service.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
403:
description: |-
The credentials supplied by the homeserver were rejected.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml
404:
description: |-
The application service indicates that this user does not exist.
Optional error information can be included in the body of this response.
examples:
application/json: {
"errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
}
schema:
$ref: ../client-server/definitions/errors/error.yaml

74
api/application-service/transactions.yaml Normal file
View file

@ -0,0 +1,74 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Application Service API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: "/"
produces:
- application/json
paths:
"/transactions/{txnId}":
put:
summary: Send some events to the application service.
description: |-
This API is called by the homeserver when it wants to push an event
(or batch of events) to the application service.
Note that the application service should distinguish state events
from message events via the presence of a ``state_key``, rather than
via the event type.
operationId: sendTransaction
parameters:
- in: path
name: txnId
type: string
description: |-
The transaction ID for this set of events. Homeservers generate
these IDs and they are used to ensure idempotency of requests.
required: true
x-example: "35"
- in: body
name: body
description: A list of events.
schema:
type: object
example: {
"events": [
{"$ref": "../../event-schemas/examples/m.room.member"},
{"$ref": "../../event-schemas/examples/m.room.message#m.text"}
]
}
description: Transaction information
properties:
events:
type: array
description: |-
A list of events, formatted as per the Client-Server API.
items:
type: object
title: Event
required: ["events"]
responses:
200:
description: The transaction was processed successfully.
examples:
application/json: {}
schema:
type: object

77
api/check_examples.py
View file

@ -43,28 +43,23 @@ except ImportError as e:
raise
def check_schema(filepath, example, schema):
example = resolve_references(filepath, example)
schema = resolve_references(filepath, schema)
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_file})
jsonschema.validate(example, schema, resolver=resolver)
def check_parameter(filepath, request, parameter):
schema = parameter.get("schema")
example = None
try:
example_json = schema.get('example')
if example_json and not schema.get("format") == "byte":
example = json.loads(example_json)
except Exception as e:
raise ValueError("Error parsing JSON example request for %r" % (
request
), e)
fileurl = "file://" + os.path.abspath(filepath)
example = schema.get('example')
if example and schema:
try:
print ("Checking request schema for: %r %r" % (
print("Checking request schema for: %r %r" % (
filepath, request
))
# Setting the 'id' tells jsonschema where the file is so that it
# can correctly resolve relative $ref references in the schema
schema['id'] = fileurl
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
jsonschema.validate(example, schema, resolver=resolver)
check_schema(filepath, example, schema)
except Exception as e:
raise ValueError("Error validating JSON schema for %r" % (
request
@ -72,27 +67,14 @@ def check_parameter(filepath, request, parameter):
def check_response(filepath, request, code, response):
example = None
try:
example_json = response.get('examples', {}).get('application/json')
if example_json:
example = json.loads(example_json)
except Exception as e:
raise ValueError("Error parsing JSON example response for %r %r" % (
request, code
), e)
example = response.get('examples', {}).get('application/json')
schema = response.get('schema')
fileurl = "file://" + os.path.abspath(filepath)
if example and schema:
try:
print ("Checking response schema for: %r %r %r" % (
filepath, request, code
))
# Setting the 'id' tells jsonschema where the file is so that it
# can correctly resolve relative $ref references in the schema
schema['id'] = fileurl
resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
jsonschema.validate(example, schema, resolver=resolver)
check_schema(filepath, example, schema)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
request, code
@ -119,12 +101,39 @@ def check_swagger_file(filepath):
check_response(filepath, request, code, response)
def load_yaml(path):
if not path.startswith("file:///"):
def resolve_references(path, schema):
if isinstance(schema, dict):
# do $ref first
if '$ref' in schema:
value = schema['$ref']
path = os.path.abspath(os.path.join(os.path.dirname(path), value))
ref = load_file("file://" + path)
result = resolve_references(path, ref)
del schema['$ref']
else:
result = {}
for key, value in schema.items():
result[key] = resolve_references(path, value)
return result
elif isinstance(schema, list):
return [resolve_references(path, value) for value in schema]
else:
return schema
def load_file(path):
print("Loading reference: %s" % path)
if not path.startswith("file://"):
raise Exception("Bad ref: %s" % (path,))
path = path[len("file://"):]
with open(path, "r") as f:
return yaml.load(f)
if path.endswith(".json"):
return json.load(f)
else:
# We have to assume it's YAML because some of the YAML examples
# do not have file extensions.
return yaml.load(f)
if __name__ == '__main__':

10
api/client-server/account-data.yaml
View file

@ -34,6 +34,7 @@ paths:
Set some account_data for the client. This config is only visible to the user
that set the account_data. The config will be synced to clients in the
top-level ``account_data``.
operationId: setAccountData
security:
- accessToken: []
parameters:
@ -60,8 +61,8 @@ paths:
The content of the account_data
schema:
type: object
example: |-
{"custom_account_data_key": "custom_config_value"}
example: {
"custom_account_data_key": "custom_config_value"}
responses:
200:
description:
@ -75,6 +76,7 @@ paths:
Set some account_data for the client on a given room. This config is only
visible to the user that set the account_data. The config will be synced to
clients in the per-room ``account_data``.
operationId: setAccountDataPerRoom
security:
- accessToken: []
parameters:
@ -108,8 +110,8 @@ paths:
The content of the account_data
schema:
type: object
example: |-
{"custom_account_data_key": "custom_account_data_value"}
example: {
"custom_account_data_key": "custom_account_data_value"}
responses:
200:
description:

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

@ -36,6 +36,7 @@ paths:
This API may be restricted to only be called by the user being looked
up, or by a server admin. Server-local administrator privileges are not
specified in this document.
operationId: getWhoIs
security:
- accessToken: []
parameters:
@ -49,8 +50,7 @@ paths:
200:
description: The lookup was successful.
examples:
application/json: |-
{
application/json: {
"user_id": "@peter:rabbit.rocks",
"devices": {
"teapot": {
@ -105,7 +105,8 @@ paths:
type: string
description: Most recently seen IP address of the session.
last_seen:
type: number
type: integer
format: int64
description: Unix timestamp that the session was last active.
user_agent:
type: string

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

@ -39,14 +39,14 @@ paths:
Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password.
operationId: getAccount3PIDs
security:
- accessToken: []
responses:
200:
description: The lookup was successful.
examples:
application/json: |-
{
application/json: {
"threepids": [
{
"medium": "email",
@ -66,7 +66,7 @@ paths:
medium:
type: string
description: The medium of the third party identifier.
enum: ["email"]
enum: ["email", "msisdn"]
address:
type: string
description: The third party identifier address.
@ -75,6 +75,7 @@ paths:
post:
summary: Adds contact information to the user's account.
description: Adds contact information to the user's account.
operationId: post3PIDs
security:
- accessToken: []
parameters:
@ -106,8 +107,7 @@ paths:
server. Default: ``false``.
x-example: true
required: ["three_pid_creds"]
example: |-
{
example: {
"three_pid_creds": {
"id_server": "matrix.org",
"sid": "abc123987",
@ -119,17 +119,18 @@ paths:
200:
description: The addition was successful.
examples:
application/json: "{}"
application/json: {}
schema:
type: object
403:
description: The credentials could not be verified with the identity server.
examples:
application/json: |-
{
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- User data
"/account/3pid/email/requestToken":
@ -142,6 +143,21 @@ paths:
validation tokens when adding an email address to an account. This API's
parameters and response is identical to that of the HS API
|/register/email/requestToken|_ endpoint.
operationId: requestTokenTo3PIDEmail
responses:
200:
description: An email was sent to the given address
description: An email was sent to the given address.
"/account/3pid/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given email address for the purpose of adding a phone number to an account.
description: |-
Proxies the identity server API ``validate/msisdn/requestToken``, but
first checks that the given phone number is **not** already associated
with an account on this Home Server. This API should be used to request
validation tokens when adding a phone number to an account. This API's
parameters and response is identical to that of the HS API
|/register/msisdn/requestToken|_ endpoint.
operationId: requestTokenTo3PIDMSISDN
responses:
200:
description: An SMS message was sent to the given phone number.

88
api/client-server/appservice_room_directory.yaml Normal file
View file

@ -0,0 +1,88 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Application Service Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
produces:
- application/json
securityDefinitions:
# Note: this is the same access_token definition used elsewhere in the client
# server API, however this expects an access token for an application service.
$ref: definitions/security.yaml
paths:
"/directory/list/appservice/{networkId}/{roomId}":
put:
summary: |-
Updates a room's visibility in the application service's room directory.
description: |-
Updates the visibility of a given room on the application service's room
directory.
This API is similar to the room directory visibility API used by clients
to update the homeserver's more general room directory.
This API requires the use of an application service access token (``as_token``)
instead of a typical client's access_token. This API cannot be invoked by
users who are not identified as application services.
operationId: updateAppserviceRoomDirectoryVsibility
parameters:
- in: path
type: string
name: networkId
description: |-
The protocol (network) ID to update the room list for. This would
have been provided by the application service as being listed as
a supported protocol.
required: true
x-example: "irc"
- in: path
type: string
name: roomId
description: The room ID to add to the directory.
required: true
x-example: "!somewhere:domain.com"
- in: body
name: body
required: true
schema:
type: object
properties:
visibility:
type: string
enum: ["public", "private"]
description: |-
Whether the room should be visible (public) in the directory
or not (private).
example: "public"
required: ['visibility']
security:
# again, this is the appservice's token - not a typical client's
- accessToken: []
responses:
200:
description: The room's directory visibility has been updated.
schema:
type: object
examples:
application/json: {}
tags:
- Application service room directory management

29
api/client-server/banning.yaml
View file

@ -36,6 +36,7 @@ paths:
When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
The caller must have the required power level in order to perform this operation.
operationId: ban
security:
- accessToken: []
parameters:
@ -50,8 +51,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
@ -61,14 +61,15 @@ paths:
description: The fully qualified user ID of the user being banned.
reason:
type: string
description: The reason the user has been banned.
description: The reason the user has been banned. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
description: The user has been kicked and banned from the room.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
403:
@ -78,11 +79,12 @@ paths:
- The banner is not currently in the room.
- The banner's power level is insufficient to ban users from the room.
examples:
application/json: |-
{
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership
"/rooms/{roomId}/unban":
@ -93,6 +95,7 @@ paths:
and join if they would otherwise be allowed to join according to its join rules.
The caller must have the required power level in order to perform this operation.
operationId: unban
security:
- accessToken: []
parameters:
@ -107,8 +110,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
@ -120,8 +122,8 @@ paths:
200:
description: The user has been unbanned from the room.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
403:
@ -130,10 +132,11 @@ paths:
- The unbanner's power level is insufficient to unban users from the room.
examples:
application/json: |-
{
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

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

@ -37,6 +37,7 @@ paths:
``redirectUrl=https://client.example.com/?q=p``, it might redirect to
``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``.
operationId: redirectToCAS
parameters:
- in: query
type: string

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

@ -39,6 +39,7 @@ paths:
If validation is unsuccessful, the server should respond with a ``401
Unauthorized`` error, the body of which will be displayed to the user.
operationId: loginByCASTicket
parameters:
- in: query
type: string

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

@ -18,15 +18,24 @@ info:
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
consumes:
- application/json
- "*/*"
produces:
- application/json
- "*/*"
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/upload":
post:
summary: Upload some content to the content repository.
operationId: uploadContent
produces: ["application/json"]
security:
- accessToken: []
parameters:
- in: header
name: Content-Type
@ -57,15 +66,19 @@ paths:
type: string
description: "The MXC URI to the uploaded content."
examples:
"application/json": |-
{
application/json: {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}":
get:
summary: "Download content from the content repository."
operationId: getContent
produces: ["*/*"]
parameters:
- in: path
@ -82,6 +95,16 @@ paths:
required: true
description: |
The media ID from the ``mxc://`` URI (the path component)
- 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.
responses:
200:
description: "The content that was previously uploaded."
@ -94,11 +117,16 @@ paths:
type: "string"
schema:
type: file
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/download/{serverName}/{mediaId}/{fileName}":
get:
summary: "Download content from the content repository as a given filename."
operationId: getContentOverrideName
produces: ["*/*"]
parameters:
- in: path
@ -122,6 +150,16 @@ paths:
required: true
description: |
The filename to give in the Content-Disposition
- 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.
responses:
200:
description: "The content that was previously uploaded."
@ -134,11 +172,16 @@ paths:
type: "string"
schema:
type: file
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/thumbnail/{serverName}/{mediaId}":
get:
summary: "Download a thumbnail of the content from the content repository."
operationId: getContentThumbnail
produces: ["image/jpeg", "image/png"]
parameters:
- in: path
@ -175,6 +218,16 @@ paths:
name: method
x-example: "scale"
description: The desired resizing method.
- 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.
responses:
200:
description: "A thumbnail of the requested content."
@ -185,5 +238,108 @@ paths:
enum: ["image/jpeg", "image/png"]
schema:
type: file
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/preview_url":
get:
summary: "Get information about a URL for a client"
operationId: getUrlPreview
produces: ["application/json"]
security:
- accessToken: []
parameters:
- in: query
type: string
x-example: "https://matrix.org"
name: url
description: "The URL to get a preview of"
required: true
- in: query
type: integer
format: int64
x-example: 1510610716656
name: ts
description: |-
The preferred point in time to return a preview for. The server may
return a newer version if it does not have the requested version
available.
responses:
200:
description: |-
The OpenGraph data for the URL, which may be empty. Some values are
replaced with matrix equivalents if they are provided in the response.
The differences from the OpenGraph protocol are described here.
schema:
type: object
properties:
"matrix:image:size":
type: integer
format: int64
description: |-
The byte-size of the image. Omitted if there is no image attached.
"og:image":
type: string
description: |-
An MXC URI to the image. Omitted if there is no image.
examples:
application/json: {
"og:title": "Matrix Blog Post",
"og:description": "This is a really cool blog post from matrix.org",
"og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
"og:image:type": "image/png",
"og:image:height": 48,
"og:image:width": 48,
"matrix:image:size": 102400
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Media
"/config":
get:
summary: Get the configuration for the content repository.
description: |-
This endpoint allows clients to retrieve the configuration of the content
repository, such as upload limitations.
Clients SHOULD use this as a guide when using content repository endpoints.
All values are intentionally left optional. Clients SHOULD follow
the advice given in the field description when the field is not available.
**NOTE:** Both clients and server administrators should be aware that proxies
between the client and the server may affect the apparent behaviour of content
repository APIs, for example, proxies may enforce a lower upload size limit
than is advertised by the server on this endpoint.
operationId: getConfig
produces: ["application/json"]
security:
- accessToken: []
responses:
200:
description: The public content repository configuration for the matrix server.
schema:
type: object
properties:
m.upload.size:
type: integer
format: int64
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.
examples:
application/json: {
"m.upload.size": 50000000
}
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Media

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

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -37,15 +38,36 @@ paths:
the new room, including checking power levels for each event. It MUST
apply the events implied by the request in the following order:
1. Events set by ``presets``.
0. 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``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
2. Events listed in ``initial_state``, in the order that they are
listed.
3. Events implied by ``name`` and ``topic``.
3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
state events).
4. Invite events implied by ``invite`` and ``invite_3pid``.
4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
``membership: invite`` and ``m.room.third_party_invite``).
The available presets do the following with respect to room state:
======================== ============== ====================== ================ =========
Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other
======================== ============== ====================== ================ =========
``private_chat`` ``invite`` ``shared`` ``can_join``
``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.
``public_chat`` ``public`` ``shared`` ``forbidden``
======================== ============== ====================== ================ =========
The server will create a ``m.room.create`` event in the room with the
requesting user as the creator, alongside other keys provided in the
``creation_content``.
operationId: createRoom
security:
- accessToken: []
parameters:
@ -54,16 +76,15 @@ paths:
description: The desired room configuration.
schema:
type: object
example: |-
{
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
example: {
"preset": "public_chat",
"room_alias_name": "thepub",
"name": "The Grand Duke Pub",
"topic": "All about happy hour",
"creation_content": {
"m.federate": false
}
}
properties:
visibility:
type: string
@ -84,6 +105,9 @@ paths:
created the room. For example, if this was set to "foo" and
sent to the homeserver "example.com" the complete room alias
would be ``#foo:example.com``.
The complete room alias will become the canonical alias for
the room.
name:
type: string
description: |-
@ -123,14 +147,22 @@ paths:
type: string
description: The invitee's third party identifier.
required: ["id_server", "medium", "address"]
room_version:
type: string
description: |-
The room version to set for the room. If not provided, the homeserver is
to use its configured default. If provided, the homeserver will return a
400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not
support the room version.
example: "1"
creation_content:
title: CreationContent
type: object
description: |-
Extra keys to be added to the content of the ``m.room.create``.
The server will clobber the following keys: ``creator``. Future
versions of the specification may allow the server to clobber
other keys.
Extra keys, such as ``m.federate``, to be added to the content
of the `m.room.create`_ event. The server will clobber the following
keys: ``creator``, ``room_version``. Future versions of the specification
may allow the server to clobber other keys.
initial_state:
type: array
description: |-
@ -139,7 +171,7 @@ paths:
room. The expected format of the state events are an object
with type, state_key and content keys set.
Takes precedence over events set by ``presets``, but gets
Takes precedence over events set by ``preset``, but gets
overriden by ``name`` and ``topic`` keys.
items:
type: object
@ -147,35 +179,39 @@ paths:
properties:
type:
type: string
description: The type of event to send.
state_key:
type: string
description: The state_key of the state event. Defaults to an empty string.
content:
type: string
type: object
description: The content of the event.
required: ["type", "content"]
preset:
type: string
enum: ["private_chat", "public_chat", "trusted_private_chat"]
description: |-
Convenience parameter for setting various default state events
based on a preset. Must be either:
based on a preset.
``private_chat`` =>
``join_rules`` is set to ``invite``.
``history_visibility`` is set to ``shared``.
``trusted_private_chat`` =>
``join_rules`` is set to ``invite``.
``history_visibility`` is set to ``shared``.
All invitees are given the same power level as the room creator.
``public_chat``: =>
``join_rules`` is set to ``public``.
``history_visibility`` is set to ``shared``.
If unspecified, the server should use the ``visibility`` to determine
which preset to use. A visbility of ``public`` equates to a preset of
``public_chat`` and ``private`` visibility equates to a preset of
``private_chat``.
is_direct:
type: boolean
description: |-
This flag makes the server set the ``is_direct`` flag on the
``m.room.member`` events sent to the users in ``invite`` and
``invite_3pid``. See `Direct Messaging`_ for more information.
power_level_content_override:
title: Power Level Event Content
type: object
description: |-
The power level content to override in the default power level
event. This object is applied on top of the generated `m.room.power_levels`_
event content prior to it being sent to the room. Defaults to
overriding nothing.
responses:
200:
description: Information about the newly created room.
@ -187,11 +223,11 @@ paths:
type: string
description: |-
The created room's ID.
required: ['room_id']
examples:
application/json: |-
{
"room_id": "!sefiuhWgwghwWgh:example.com"
}
application/json: {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
400:
description: |-
@ -208,6 +244,7 @@ paths:
invalid: for example, the user's ``power_level`` is set below
that necessary to set the room name (``errcode`` set to
``M_INVALID_ROOM_STATE``).
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room creation

68
api/client-server/definitions/device_keys.yaml Normal file
View file

@ -0,0 +1,68 @@
# Copyright 2016 OpenMarket Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: DeviceKeys
description: Device identity keys
properties:
user_id:
type: string
description: |-
The ID of the user the device belongs to. Must match the user ID used
when logging in.
example: "@alice:example.com"
device_id:
type: string
description: |-
The ID of the device these keys belong to. Must match the device ID used
when logging in.
example: "JLAFKJWSCS"
algorithms:
type: array
items:
type: string
description: |-
The encryption algorithms supported by this device.
example: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"]
keys:
type: object
description: |-
Public identity keys. The names of the properties should be in the
format ``<algorithm>:<device_id>``. The keys themselves should be
encoded as specified by the key algorithm.
additionalProperties:
type: string
example:
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI"
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
signatures:
type: object
description: |-
Signatures for the device key object. A map from user ID, to a map from
``<algorithm>:<device_id>`` to the signature.
The signature is calculated using the process described at `Signing
JSON`_.
additionalProperties:
type: object
additionalProperties:
type: string
example:
"@alice:example.com":
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
required:
- user_id
- device_id
- algorithms
- keys
- signatures

2
api/client-server/definitions/error.yaml → api/client-server/definitions/errors/error.yaml
View file

@ -17,7 +17,9 @@ properties:
errcode:
type: string
description: An error code.
example: M_UNKNOWN
error:
type: string
description: A human-readable error message.
example: An unknown error occurred
required: ["errcode"]

32
api/client-server/definitions/errors/rate_limited.yaml Normal file
View file

@ -0,0 +1,32 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
$ref: error.yaml
type: object
description: The rate limit was reached for this request
properties:
errcode:
type: string
description: The M_LIMIT_EXCEEDED error code
example: M_LIMIT_EXCEEDED
error:
type: string
description: A human-readable error message.
example: Too many requests
retry_after_ms:
type: integer
description: |-
The amount of time in milliseconds the client should wait
before trying the request again.
example: 2000
required: ["errcode"]

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

@ -12,6 +12,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
properties:
event_id:
description: The ID of this event, if applicable.
type: string
content:
description: The content of this event. The fields in this object will vary depending
on the type of event.

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

@ -11,7 +11,7 @@
# 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.
title: Filter
title: EventFilter
properties:
limit:
description: The maximum number of events to return.

105
api/client-server/definitions/public_rooms_response.yaml Normal file
View file

@ -0,0 +1,105 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
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.
example: {
"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
}

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

@ -13,23 +13,23 @@
# limitations under the License.
allOf:
- $ref: event_filter.yaml
title: RoomEventFilter
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.
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included.
items:
type: string
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a url key in their content. If
``false``, excludes those events.
type: object
- type: object
title: RoomEventFilter
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.
items:
type: string
type: array
rooms:
description: A list of room IDs to include. If this list is absent then all rooms
are included.
items:
type: string
type: array
contains_url:
type: boolean
description: If ``true``, includes only events with a ``url`` key in their content. If
``false``, excludes those events. Defaults to ``false``.

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

@ -11,6 +11,8 @@
# 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: Filter
properties:
event_fields:
description: List of event fields to include. If this list is absent then all
@ -40,6 +42,7 @@ properties:
room:
title: RoomFilter
description: Filters to be applied to room data.
type: object
properties:
not_rooms:
description: A list of room IDs to exclude. If this list is absent then no rooms
@ -76,5 +79,3 @@ properties:
allOf:
- $ref: room_event_filter.yaml
description: The per user account data to include for rooms.
type: object
type: object

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

@ -19,7 +19,7 @@ properties:
on the filter
type: boolean
prev_batch:
description: A token that can be supplied to to the ``from`` parameter of the
description: A token that can be supplied to the ``from`` parameter of the
rooms/{roomId}/messages endpoint
type: string
type: object

24
api/client-server/definitions/user_identifier.yaml Normal file
View file

@ -0,0 +1,24 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
title: User identifier
description: |-
Identification information for a user
type: object
properties:
type:
type: string
description: The type of identification. See `Identifier types`_ for supported values and additional property descriptions.
required:
- type
additionalProperties: true

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

@ -33,6 +33,7 @@ paths:
summary: List registered devices for the current user
description: |-
Gets information about all devices for the current user.
operationId: getDevices
security:
- accessToken: []
responses:
@ -49,8 +50,7 @@ paths:
allOf:
- $ref: "definitions/client_device.yaml"
examples:
application/json: |-
{
application/json: {
"devices": [
{
"device_id": "QBUAZIFURK",
@ -67,6 +67,7 @@ paths:
summary: Get a single device
description: |-
Gets information on a single device, by device id.
operationId: getDevice
security:
- accessToken: []
parameters:
@ -84,8 +85,7 @@ paths:
allOf:
- $ref: "definitions/client_device.yaml"
examples:
application/json: |-
{
application/json: {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
@ -99,6 +99,7 @@ paths:
summary: Update a device
description: |-
Updates the metadata on the given device.
operationId: updateDevice
security:
- accessToken: []
parameters:
@ -125,8 +126,8 @@ paths:
200:
description: The device was successfully updated.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
404:
@ -138,7 +139,8 @@ paths:
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
Deletes the given device, and invalidates any access token assoicated with it.
Deletes the given device, and invalidates any access token associated with it.
operationId: deleteDevice
security:
- accessToken: []
parameters:
@ -166,8 +168,55 @@ paths:
schema:
type: object
examples:
application/json: |-
{}
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.
schema:
"$ref": "definitions/auth_response.yaml"
tags:
- Device management
"/delete_devices":
post:
summary: Bulk deletion of devices
description: |-
This API endpoint uses the `User-Interactive Authentication API`_.
Deletes the given devices, and invalidates any access token associated with them.
operationId: deleteDevices
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
devices:
type: array
description: The list of device IDs to delete.
items:
type: string
description: A list of device IDs.
example: ["QBUAZIFURK", "AUIECTSRND"]
auth:
description: |-
Additional authentication information for the
user-interactive authentication API.
"$ref": "definitions/auth_data.yaml"
required:
- devices
responses:
200:
description: |-
The devices were successfully removed, or had been removed
previously.
schema:
type: object
examples:
application/json: {
}
401:
description: |-
The homeserver requires additional authentication information.

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

@ -30,6 +30,7 @@ paths:
"/room/{roomAlias}":
put:
summary: Create a new mapping from room alias to room ID.
operationId: setRoomAlias
security:
- accessToken: []
parameters:
@ -40,7 +41,7 @@ paths:
required: true
x-example: "#monkeys:matrix.org"
- in: body
name: roomInfo
name: body
description: Information about this room alias.
required: true
schema:
@ -49,26 +50,26 @@ paths:
room_id:
type: string
description: The room ID to set.
example: |-
{
"room_id": "!abnjk1jdasj98:capuchins.com"
}
required: ['room_id']
example: {
"room_id": "!abnjk1jdasj98:capuchins.com"
}
responses:
200:
description: The mapping was created.
examples:
application/json: |-
{}
application/json: {}
schema:
type: object
409:
description: A room alias with that name already exists.
examples:
application/json: |-
{
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
application/json: {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
get:
@ -80,6 +81,7 @@ paths:
domain part of the alias does not correspond to the server's own
domain.
operationId: getRoomIdByAlias
parameters:
- in: path
type: string
@ -98,13 +100,12 @@ paths:
description: The room ID for this room alias.
servers:
type: array
description: A list of servers that are aware of this room ID.
description: A list of servers that are aware of this room alias.
items:
type: string
description: A server which is aware of this room ID.
description: A server which is aware of this room alias.
examples:
application/json: |-
{
application/json: {
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
@ -115,11 +116,12 @@ paths:
404:
description: There is no mapped room ID for this room alias.
examples:
application/json: |-
{
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room ID !abnjk1jdasj98:capuchins.com not found."
"error": "Room alias #monkeys:matrix.org not found."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room directory
delete:
@ -128,6 +130,7 @@ paths:
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.
operationId: deleteRoomAlias
security:
- accessToken: []
parameters:
@ -141,8 +144,8 @@ paths:
200:
description: The mapping was deleted.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
tags:

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

@ -34,6 +34,7 @@ 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.
operationId: getEventContext
security:
- accessToken: []
parameters:
@ -99,8 +100,7 @@ paths:
allOf:
- "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
examples:
application/json: |-
{
application/json: {
"end": "t29-57_2_0_2",
"events_after": [
{

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

@ -33,6 +33,7 @@ paths:
Uploads a new filter definition to the homeserver.
Returns a filter ID that may be used in future requests to
restrict which events are returned to the client.
operationId: defineFilter
security:
- accessToken: []
parameters:
@ -52,52 +53,54 @@ paths:
type: object
allOf:
- $ref: "definitions/sync_filter.yaml"
example: |-
{
"room": {
"state": {
"types": ["m.room.*"],
"not_rooms": ["!726s6s6q:example.com"]
},
"timeline": {
"limit": 10,
"types": ["m.room.message"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
},
"ephemeral": {
"types": ["m.receipt", "m.typing"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
}
example: {
"room": {
"state": {
"types": ["m.room.*"],
"not_rooms": ["!726s6s6q:example.com"]
},
"presence": {
"types": ["m.presence"],
"not_senders": ["@alice:example.com"]
"timeline": {
"limit": 10,
"types": ["m.room.message"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
},
"event_format": "client",
"event_fields": ["type", "content", "sender"]
}
"ephemeral": {
"types": ["m.receipt", "m.typing"],
"not_rooms": ["!726s6s6q:example.com"],
"not_senders": ["@spam:example.com"]
}
},
"presence": {
"types": ["m.presence"],
"not_senders": ["@alice:example.com"]
},
"event_format": "client",
"event_fields": ["type", "content", "sender"]
}
responses:
200:
description: The filter was created.
examples:
application/json: |-
{
"filter_id": "66696p746572"
}
schema:
type: object
properties:
filter_id:
type: string
description: |-
The ID of the filter that was created.
The ID of the filter that was created. Cannot start
with a ``{`` as this character is used to determine
if the filter provided is inline JSON or a previously
declared filter by homeservers on some APIs.
example: "66696p746572"
required: ['filter_id']
tags:
- Room participation
"/user/{userId}/filter/{filterId}":
get:
summary: Download a filter
operationId: getFilter
security:
- accessToken: []
parameters:
- in: path
name: userId
@ -118,8 +121,7 @@ paths:
description: |-
"The filter defintion"
examples:
application/json: |-
{
application/json: {
"room": {
"state": {
"types": ["m.room.*"],
@ -148,5 +150,7 @@ paths:
type: object
allOf:
- $ref: "definitions/sync_filter.yaml"
404:
description: "Unknown filter."
tags:
- Room participation

16
api/client-server/inviting.yaml
View file

@ -51,6 +51,7 @@ paths:
``m.room.member`` event to the room.
.. _third party invites section: `invite-by-third-party-id-endpoint`_
operationId: inviteUser
security:
- accessToken: []
parameters:
@ -65,8 +66,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"user_id": "@cheeky_monkey:matrix.org"
}
properties:
@ -78,8 +78,8 @@ paths:
200:
description: The user has been invited to join the room.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
403:
@ -91,11 +91,13 @@ paths:
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

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

@ -44,6 +44,7 @@ paths:
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: []
parameters:
@ -57,8 +58,7 @@ paths:
name: third_party_signed
schema:
type: object
example: |-
{
example: {
"third_party_signed": {
"sender": "@cat:the.hat",
"mxid": "@green:eggs.ham",
@ -97,8 +97,8 @@ paths:
The joined room ID must be returned in the ``room_id`` field.
examples:
application/json: |-
{"room_id": "!d41d8cd:matrix.org"}
application/json: {
"room_id": "!d41d8cd:matrix.org"}
schema:
type: object
403:
@ -108,12 +108,14 @@ paths:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/join/{roomIdOrAlias}":
@ -133,6 +135,7 @@ paths:
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: []
parameters:
@ -142,12 +145,20 @@ paths:
description: The room identifier or alias to join.
required: true
x-example: "#monkeys:matrix.org"
- in: query
type: array
items:
type: string
name: server_name
description: |-
The servers to attempt to join the room through. One of the servers
must be participating in the room.
x-example: ["matrix.org", "elsewhere.ca"]
- in: body
name: third_party_signed
schema:
type: object
example: |-
{
example: {
"third_party_signed": {
"signed": {
"sender": "@cat:the.hat",
@ -193,8 +204,8 @@ paths:
The joined room ID must be returned in the ``room_id`` field.
examples:
application/json: |-
{"room_id": "!d41d8cd:matrix.org"}
application/json: {
"room_id": "!d41d8cd:matrix.org"}
schema:
type: object
403:
@ -204,11 +215,13 @@ paths:
- The room is invite-only and the user was not invited.
- The user has been banned from the room.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
application/json: {
"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

357
api/client-server/keys.yaml Normal file
View file

@ -0,0 +1,357 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Client Config 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:
"/keys/upload":
post:
summary: Upload end-to-end encryption keys.
description: |-
Publishes end-to-end encryption keys for the device.
operationId: uploadKeys
security:
- accessToken: []
parameters:
- in: body
name: keys
description: |-
The keys to be published
schema:
type: object
properties:
device_keys:
description: |-
Identity keys for the device. May be absent if no new
identity keys are required.
allOf:
- $ref: definitions/device_keys.yaml
one_time_keys:
type: object
description: |-
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.
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"
responses:
200:
description:
The provided keys were sucessfully uploaded.
schema:
type: object
properties:
one_time_key_counts:
type: object
additionalProperties:
type: integer
description: |-
For each key algorithm, the number of unclaimed one-time keys
of that type currently held on the server for this device.
example:
curve25519: 10
signed_curve25519: 20
required:
- one_time_key_counts
tags:
- End-to-end encryption
"/keys/query":
post:
summary: Download device identity keys.
description: |-
Returns the current devices and identity keys for the given users.
operationId: queryKeys
security:
- accessToken: []
parameters:
- in: body
name: query
description: |-
Query defining the keys to be downloaded
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
device_keys:
type: object
description: |-
The keys to be downloaded. A map from user ID, to a list of
device IDs, or to an empty list to indicate all devices for the
corresponding user.
additionalProperties:
type: array
items:
type: string
description: "device ID"
example:
"@alice:example.com": []
token:
type: string
description: |-
If the client is fetching keys as a result of a device update received
in a sync request, this should be the 'since' token of that sync request,
or any later sync token. This allows the server to ensure its response
contains the keys advertised by the notification in that sync.
required:
- device_keys
responses:
200:
description:
The device information
schema:
type: object
properties:
failures:
type: object
description: |-
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 ``device_keys`` result.
additionalProperties:
type: object
example: {}
device_keys:
type: object
description: |-
Information on the queried devices. A map from user ID, to a
map from device ID to device information. For each device,
the information returned will be the same as uploaded via
``/keys/upload``, with the addition of an ``unsigned``
property.
additionalProperties:
type: object
additionalProperties:
allOf:
- $ref: definitions/device_keys.yaml
properties:
unsigned:
title: UnsignedDeviceInfo
type: object
description: |-
Additional data added to the device key information
by intermediate servers, and not covered by the
signatures.
properties:
device_display_name:
type: string
description:
The display name which the user set on the device.
example:
"@alice:example.com":
JLAFKJWSCS: {
"user_id": "@alice:example.com",
"device_id": "JLAFKJWSCS",
"algorithms": [
"m.olm.v1.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"unsigned": {
"device_display_name": "Alice's mobile phone"
}
}
tags:
- End-to-end encryption
"/keys/claim":
post:
summary: Claim one-time encryption keys.
description: |-
Claims one-time keys for use in pre-key messages.
operationId: claimKeys
security:
- accessToken: []
parameters:
- in: body
name: query
description: |-
Query defining the keys to be claimed
schema:
type: object
properties:
timeout:
type: integer
description: |-
The time (in milliseconds) to wait when downloading keys from
remote servers. 10 seconds is the recommended default.
example: 10000
one_time_keys:
type: object
description: |-
The keys to be claimed. A map from user ID, to a map from
device ID to algorithm name.
additionalProperties:
type: object
additionalProperties:
type: string
description: algorithm
example: "signed_curve25519"
example:
"@alice:example.com": { "JLAFKJWSCS": "signed_curve25519" }
required:
- one_time_keys
responses:
200:
description:
The claimed keys
schema:
type: object
properties:
failures:
type: object
description: |-
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.
additionalProperties:
type: object
example: {}
one_time_keys:
type: object
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.
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"
tags:
- End-to-end encryption
"/keys/changes":
get:
summary: Query users with recent device key updates.
description: |-
Gets a list of users who have updated their device identity keys since a
previous sync token.
The server should include in the results any users who:
* currently share a room with the calling user (ie, both users have
membership state ``join``); *and*
* added new device identity keys or removed an existing device with
identity keys, between ``from`` and ``to``.
operationId: getKeysChanges
security:
- accessToken: []
parameters:
- in: query
name: from
type: string
description: |-
The desired start point of the list. Should be the ``next_batch`` field
from a response to an earlier call to |/sync|. Users who have not
uploaded new device identity keys since this point, nor deleted
existing devices with identity keys since then, will be excluded
from the results.
required: true
x-example: "s72594_4483_1934"
- in: query
name: to
type: string
description: |-
The desired end point of the list. Should be the ``next_batch``
field from a recent call to |/sync| - typically the most recent
such call. This may be used by the server as a hint to check its
caches are up to date.
required: true
x-example: "s75689_5632_2435"
responses:
200:
description:
The list of users who updated their devices.
schema:
type: object
properties:
changed:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who updated their device
identity keys.
example: ["@alice:example.com", "@bob:example.org"]
left:
type: array
items:
type: string
description: |-
The Matrix User IDs of all users who may have left all
the end-to-end encrypted rooms they previously shared
with the user.
example: ["@clara:example.com", "@doug:example.org"]
tags:
- End-to-end encryption

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

@ -34,6 +34,11 @@ paths:
Kick a user from the room.
The caller must have the required power level in order to perform this operation.
Kicking a user adjusts the target member's membership state to be ``leave`` with an
optional ``reason``. Like with other membership changes, a user can directly adjust
the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
operationId: kick
security:
- accessToken: []
parameters:
@ -48,8 +53,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
}
@ -59,14 +63,16 @@ paths:
description: The fully qualified user ID of the user being kicked.
reason:
type: string
description: The reason the user has been kicked.
description: |-
The reason the user has been kicked. This will be supplied as the
``reason`` on the target's updated `m.room.member`_ event.
required: ["user_id"]
responses:
200:
description: The user has been kicked from the room.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
403:
@ -77,10 +83,11 @@ paths:
- The kickee is not currently in the room.
- The kicker's power level is insufficient to kick users from the room.
examples:
application/json: |-
{
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Room membership

27
api/client-server/leaving.yaml
View file

@ -42,6 +42,7 @@ paths:
The user will still be allowed to retrieve history from the room which
they were previously allowed to see.
operationId: leaveRoom
security:
- accessToken: []
parameters:
@ -56,14 +57,14 @@ paths:
description: |-
The room has been left.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership
"/rooms/{roomId}/forget":
@ -77,8 +78,9 @@ paths:
for this room. If all users on a homeserver forget a room, the room is
eligible for deletion from that homeserver.
If the user is currently joined to the room, they will implicitly leave
the room as part of this API call.
If the user is currently joined to the room, they must leave the room
before calling this API.
operationId: forgetRoom
security:
- accessToken: []
parameters:
@ -93,13 +95,22 @@ paths:
description: |-
The room has been forgotten.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
400:
description: The user has not left the room
examples:
application/json: {
"errcode": "M_UNKNOWN",
"error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

58
api/client-server/list_joined_rooms.yaml Normal file
View file

@ -0,0 +1,58 @@
# Copyright 2017 Michael Telatynski <7t3chguy@gmail.com>
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Room Listing 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:
"/joined_rooms":
get:
summary: Lists the user's current rooms.
description: |-
This API returns a list of the user's current rooms.
operationId: getJoinedRooms
security:
- accessToken: []
responses:
200:
description: A list of the rooms the user is in.
schema:
type: object
required: ["joined_rooms"]
properties:
joined_rooms:
type: array
description: |-
The ID of each room in which the user has ``joined`` membership.
items:
type: string
examples:
application/json: {
"joined_rooms": [
"!foo:example.com"
]
}
tags:
- Room membership

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

@ -13,7 +13,7 @@
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Room Creation API"
title: "Matrix Client-Server Room Directory API"
version: "1.0.0"
host: localhost:8008
schemes:
@ -25,6 +25,92 @@ consumes:
produces:
- application/json
paths:
"/directory/list/room/{roomId}":
get:
summary: Gets the visibility of a room in the directory
description: |-
Gets the visibility of a given room on the server's public room directory.
operationId: getRoomVisibilityOnDirectory
parameters:
- in: path
type: string
name: roomId
description: The room ID.
required: true
x-example: "!curbf:matrix.org"
responses:
200:
description: The visibility of the room in the directory
schema:
type: object
properties:
visibility:
type: string
enum: ['private', 'public']
description: The visibility of the room in the directory.
examples:
application/json: {
"visibility": "public"
}
404:
description: The room is not known to the server
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
put:
summary: Sets the visibility of a room in the room directory
description: |-
Sets the visibility of a given room in the server's public room
directory.
Servers may choose to implement additional access control checks
here, for instance that room visibility can only be changed by
the room creator or a server administrator.
operationId: setRoomVisibilityOnDirectory
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The room ID.
required: true
x-example: "!curbf:matrix.org"
- in: body
name: body
required: true
description: |-
The new visibility for the room on the room directory.
schema:
type: object
properties:
visibility:
type: string
enum: ["private", "public"]
description: |-
The new visibility setting for the room.
Defaults to 'public'.
example: {
"visibility": "public"
}
responses:
200:
description: The visibility was updated, or no change was needed.
examples:
application/json: {}
404:
description: The room is not known to the server
examples:
application/json: {
"errcode": "M_NOT_FOUND",
"error": "Room not found"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/publicRooms":
get:
summary: Lists the public rooms on the server.
@ -33,10 +119,11 @@ paths:
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
operationId: getPublicRooms
parameters:
- in: query
name: limit
type: number
type: integer
description: |-
Limit the number of results returned.
- in: query
@ -57,99 +144,7 @@ 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: number
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: number
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
post:
@ -159,6 +154,7 @@ paths:
This API returns paginated responses. The rooms are ordered by the number
of joined members, with the largest rooms first.
operationId: queryPublicRooms
security:
- accessToken: []
parameters:
@ -177,7 +173,7 @@ paths:
type: object
properties:
limit:
type: number
type: integer
description: |-
Limit the number of results returned.
since:
@ -198,8 +194,26 @@ paths:
description: |-
A string to search for in the room metadata, e.g. name,
topic, canonical alias etc. (Optional).
example: |-
{"limit": 10, "filter": {"generic_search_term": "foo"}}
include_all_networks:
type: boolean
description: |-
Whether or not to include all known networks/protocols from
application services on the homeserver. Defaults to false.
example: false
third_party_instance_id:
type: string
description: |-
The specific third party network/protocol to request from the
homeserver. Can only be used if ``include_all_networks`` is false.
example: "irc"
example: {
"limit": 10,
"filter": {
"generic_search_term": "foo"
},
"include_all_networks": false,
"third_party_instance_id": "irc"
}
responses:
200:
description: A list of the rooms on the server.
@ -237,7 +251,7 @@ paths:
description: |-
The name of the room, if any.
num_joined_members:
type: number
type: integer
description: |-
The number of members joined to the room.
room_id:
@ -274,13 +288,12 @@ paths:
absence of this token means there are no results before this
batch, i.e. this is the first batch.
total_room_count_estimate:
type: number
type: integer
description: |-
An estimate on the total number of public rooms, if the
server has an estimate.
examples:
application/json: |-
{
application/json: {
"chunk": [
{
"aliases": ["#murrays:cheese.bar"],

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

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -28,6 +29,42 @@ securityDefinitions:
$ref: definitions/security.yaml
paths:
"/login":
get:
summary: Get the supported login types to authenticate users
description: |-
Gets the homeserver's supported login types to authenticate users. Clients
should pick one of these and supply it as the ``type`` when logging in.
operationId: getLoginFlows
responses:
200:
description: The login types the homeserver supports
examples:
application/json: {
"flows": [
{"type": "m.login.password"}
]
}
schema:
type: object
properties:
flows:
type: array
description: The homeserver's supported login types
items:
type: object
title: LoginFlow
properties:
type:
description: |-
The login type. This is supplied as the ``type`` when
logging in.
type: string
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management
post:
summary: Authenticates the user.
description: |-
@ -41,15 +78,18 @@ 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`_.
operationId: login
parameters:
- in: body
name: body
schema:
type: object
example: |-
{
example: {
"type": "m.login.password",
"user": "cheeky_monkey",
"identifier": {
"type": "m.id.user",
"user": "cheeky_monkey"
},
"password": "ilovebananas",
"initial_device_display_name": "Jungle Phone"
}
@ -58,15 +98,18 @@ paths:
type: string
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
description: The fully qualified user ID or just local part of the user ID, to log in.
description: The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of ``identifier``.
medium:
type: string
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.
description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of ``identifier``.
address:
type: string
description: Third party identifier for the user.
description: Third party identifier for the user. Deprecated in favour of ``identifier``.
password:
type: string
description: |-
@ -75,7 +118,7 @@ paths:
token:
type: string
description: |-
Required when ``type`` is ``m.login.token``. The login token.
Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login.
device_id:
type: string
description: |-
@ -93,11 +136,9 @@ paths:
200:
description: The user has been authenticated.
examples:
application/json: |-
{
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"home_server": "matrix.org",
"device_id": "GHTYAJCE"
}
schema:
@ -113,7 +154,13 @@ paths:
This access token can then be used to authorize other requests.
home_server:
type: string
description: The hostname of the homeserver on which the account has been registered.
description: |-
The server_name of the homeserver on which the account has
been registered.
**Deprecated**. Clients should extract the server_name from
``user_id`` (by splitting at the first colon) if they require
it. Note also that ``homeserver`` is not spelt this way.
device_id:
type: string
description: |-
@ -123,20 +170,23 @@ paths:
description: |-
Part of the request was invalid. For example, the login type may not be recognised.
examples:
application/json: |-
{
application/json: {
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: |-
The login attempt failed. For example, the password may have been incorrect.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN"}
application/json: {
"errcode": "M_FORBIDDEN"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Session management

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

@ -33,6 +33,7 @@ paths:
description: |-
Invalidates an existing access token, so that it can no longer be used for
authorization.
operationId: logout
security:
- accessToken: []
responses:
@ -43,3 +44,26 @@ paths:
properties: {}
tags:
- Session management
"/logout/all":
post:
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.
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.
operationId: logout_all
security:
- accessToken: []
responses:
200:
description: The user's access tokens were succesfully invalidated.
schema:
type: object
properties: {}
tags:
- Session management

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

@ -33,6 +33,7 @@ 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.
operationId: getRoomEvents
security:
- accessToken: []
parameters:
@ -106,9 +107,9 @@ paths:
items:
type: object
title: RoomEvent
"$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
examples:
application/json: |-
{
application/json: {
"start": "t47429-4392820_219380_26003_2265",
"end": "t47409-4357353_219380_26003_2265",
"chunk": [

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

@ -34,6 +34,7 @@ paths:
description: |-
This API is used to paginate through the list of events that the
user has been, or would have been notified about.
operationId: getNotifications
security:
- accessToken: []
parameters:
@ -44,7 +45,7 @@ paths:
required: false
x-example: "xxxxx"
- in: query
type: number
type: integer
name: limit
description: Limit on the number of events to return in this request.
required: false
@ -62,8 +63,7 @@ paths:
200:
description: A batch of events is being returned
examples:
application/json: |-
{
application/json: {
"next_token": "abcdef",
"notifications": [
{

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

@ -38,6 +38,7 @@ paths:
should instead call the |/sync|_ API with a ``since`` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: getEvents
security:
- accessToken: []
parameters:
@ -59,8 +60,7 @@ paths:
200:
description: "The events received, which may be none."
examples:
application/json: |-
{
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [
@ -115,6 +115,7 @@ paths:
should instead call the |/sync|_ API with no ``since`` parameter. See
the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: initialSync
security:
- accessToken: []
parameters:
@ -138,8 +139,7 @@ paths:
200:
description: The user's current state.
examples:
application/json: |-
{
application/json: {
"end": "s3456_9_0",
"presence": [
{
@ -407,7 +407,9 @@ paths:
retrieve this event e.g. by being a member in the room for this event.
This endpoint was deprecated in r0 of this specification. Clients
should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
should instead call the |/rooms/{roomId}/event/{eventId}|_ API
or the |/rooms/{roomId}/context/{eventId}|_ API.
operationId: getOneEvent
security:
- accessToken: []
parameters:
@ -421,8 +423,7 @@ paths:
200:
description: The full event.
examples:
application/json: |-
{
application/json: {
"content": {
"body": "Hello world!",
"msgtype": "m.text"

103
api/client-server/openid.yaml Normal file
View file

@ -0,0 +1,103 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server OpenID 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:
"/user/{userId}/openid/request_token":
post:
summary: Get an OpenID token object to verify the requester's identity.
description: |-
Gets an OpenID token object that the requester may supply to another
service to verify their identity in Matrix. The generated token is only
valid for exchanging for user information from the federation API for
OpenID.
The access token generated is only valid for the OpenID API. It cannot
be used to request another OpenID access token or call ``/sync``, for
example.
operationId: requestOpenIdToken
security:
- accessToken: []
parameters:
- in: path
type: string
name: userId
description: |-
The user to request and OpenID token for. Should be the user who
is authenticated for the request.
required: true
x-example: "@alice:example.com"
- in: body
name: body
description: An empty object. Reserved for future expansion.
required: true
schema:
type: object
example: {}
responses:
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>`_
with the only difference being the lack of an ``id_token``. Instead,
the Matrix homeserver's name is provided.
examples:
application/json: {
"access_token": "SomeT0kenHere",
"token_type": "Bearer",
"matrix_server_name": "example.com",
"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']
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- OpenID

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

@ -41,6 +41,7 @@ paths:
Note that the normal ``/events`` endpoint has been deprecated. This
API will also be deprecated at some point, but its replacement is not
yet known.
operationId: peekEvents
security:
- accessToken: []
parameters:
@ -69,8 +70,7 @@ paths:
200:
description: "The events received, which may be none."
examples:
application/json: |-
{
application/json: {
"start": "s3456_9_0",
"end": "s3457_9_0",
"chunk": [

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

@ -35,6 +35,7 @@ paths:
the activity time is updated to reflect that activity; the client does
not need to specify the ``last_active_ago`` field. You cannot set the
presence state of another user.
operationId: setPresence
security:
- accessToken: []
parameters:
@ -50,8 +51,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"presence": "online",
"status_msg": "I am here."
}
@ -68,20 +68,23 @@ paths:
200:
description: The new presence state was set.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:
summary: Get this user's presence state.
description: |-
Get the given user's presence state.
operationId: getPresence
security:
- accessToken: []
parameters:
- in: path
type: string
@ -93,8 +96,7 @@ paths:
200:
description: The presence state for this user.
examples:
application/json: |-
{
application/json: {
"presence": "unavailable",
"last_active_ago": 420845
}
@ -121,6 +123,17 @@ paths:
description: |-
There is no presence state for this user. This user may not exist or
isn't exposing presence information to you.
schema:
"$ref": "definitions/errors/error.yaml"
403:
description: You are not allowed to see this user's presence status.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "You are not allowed to see their presence"
}
schema:
"$ref": "definitions/errors/error.yaml"
tags:
- Presence
"/presence/list/{userId}":
@ -128,6 +141,7 @@ paths:
summary: Add or remove users from this presence list.
description: |-
Adds or removes users from this presence list.
operationId: modifyPresenceList
security:
- accessToken: []
parameters:
@ -143,8 +157,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"invite": [
"@bob:matrix.org"
],
@ -169,20 +182,21 @@ paths:
200:
description: The list was updated.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Presence
get:
summary: Get presence events for this presence list.
description: |-
Retrieve a list of presence events for every user on this list.
operationId: getPresenceForList
parameters:
- in: path
type: string
@ -194,8 +208,7 @@ paths:
200:
description: A list of presence events for this list.
examples:
application/json: |-
[
application/json: [
{
"content": {
"last_active_ago": 395,

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

@ -33,6 +33,7 @@ paths:
description: |-
This API sets the given user's display name. You must have permission to
set this user's display name, e.g. you need to have their ``access_token``.
operationId: setDisplayName
security:
- accessToken: []
parameters:
@ -48,8 +49,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"displayname": "Alice Margatroid"
}
properties:
@ -60,14 +60,14 @@ paths:
200:
description: The display name was set.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:
@ -76,6 +76,7 @@ paths:
Get the user's display name. This API may be used to fetch the user's
own displayname or to query the name of other users; either locally or
on remote homeservers.
operationId: getDisplayName
parameters:
- in: path
type: string
@ -87,8 +88,7 @@ paths:
200:
description: The display name for this user.
examples:
application/json: |-
{
application/json: {
"displayname": "Alice Margatroid"
}
schema:
@ -107,6 +107,7 @@ paths:
description: |-
This API sets the given user's avatar URL. You must have permission to
set this user's avatar URL, e.g. you need to have their ``access_token``.
operationId: setAvatarUrl
security:
- accessToken: []
parameters:
@ -122,8 +123,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
}
properties:
@ -134,14 +134,14 @@ paths:
200:
description: The avatar URL was set.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
get:
@ -150,6 +150,7 @@ paths:
Get the user's avatar URL. This API may be used to fetch the user's
own avatar URL or to query the URL of other users; either locally or
on remote homeservers.
operationId: getAvatarUrl
parameters:
- in: path
type: string
@ -161,8 +162,7 @@ paths:
200:
description: The avatar URL for this user.
examples:
application/json: |-
{
application/json: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
schema:
@ -183,6 +183,7 @@ paths:
to fetch the user's own profile information or other users; either
locally or on remote homeservers. This API may return keys which are not
limited to ``displayname`` or ``avatar_url``.
operationId: getUserProfile
parameters:
- in: path
type: string
@ -194,8 +195,7 @@ paths:
200:
description: The avatar URL for this user.
examples:
application/json: |-
{
application/json: {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid"
}

124
api/client-server/pusher.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -31,30 +32,30 @@ paths:
get:
summary: Gets the current pushers for the authenticated user
description: |-
Gets all currently active pushers for the authenticated user
Gets all currently active pushers for the authenticated user.
operationId: getPushers
security:
- accessToken: []
responses:
200:
description: The pushers for this user
description: The pushers for this user.
examples:
application/json: |-
{
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
application/json: {
"pushers": [
{
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A=",
"kind": "http",
"app_id": "face.mcapp.appy.prod",
"app_display_name": "Appy McAppface",
"device_display_name": "Alice's Phone",
"profile_tag": "xyz",
"lang": "en-US",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
}
]
}
}
]
}
schema:
type: object
properties:
@ -70,7 +71,7 @@ paths:
pushkey:
type: string
description: |-
This is a unique identifier for this pusher. See `/set` for
This is a unique identifier for this pusher. See ``/set`` for
more detail.
Max length, 512 bytes.
kind:
@ -115,6 +116,19 @@ paths:
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to.
format:
type: string
description: |-
The format to use when sending notifications to the Push
Gateway.
required:
- pushkey
- app_id
- kind
- app_display_name
- device_display_name
- lang
- data
tags:
- Push notifications
"/pushers/set":
@ -124,29 +138,30 @@ paths:
This endpoint allows the creation, modification and deletion of `pushers`_
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
operationId: postPusher
security:
- accessToken: []
parameters:
- in: body
name: pusher
description: The pusher information
description: The pusher information.
required: true
schema:
type: object
example: |-
{
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here"
},
"append": false
}
example: {
"lang": "en",
"kind": "http",
"app_display_name": "Mat Rix",
"device_display_name": "iPhone 9",
"profile_tag": "xxyyzz",
"app_id": "com.example.app.ios",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
"data": {
"url": "https://push-gateway.location.here/_matrix/push/v1/notify",
"format": "event_id_only"
},
"append": false
}
properties:
pushkey:
type: string
@ -157,11 +172,15 @@ paths:
for APNS or the Registration ID for GCM. If your notification
client has no such concept, use any unique identifier.
Max length, 512 bytes.
If the ``kind`` is ``"email"``, this is the email address to
send notifications to.
kind:
type: string
description: |-
The kind of pusher to configure. ``"http"`` makes a pusher that
sends HTTP pokes. ``null`` deletes the pusher.
sends HTTP pokes. ``"email"`` makes a pusher that emails the
user with unread notifications. ``null`` deletes the pusher.
app_id:
type: string
description: |-
@ -169,6 +188,8 @@ paths:
It is recommended that this end with the platform, such that
different platform versions get different app identifiers.
Max length, 64 chars.
If the ``kind`` is ``"email"``, this is ``"m.email"``.
app_display_name:
type: string
description: |-
@ -188,7 +209,7 @@ paths:
type: string
description: |-
The preferred language for receiving notifications (e.g. 'en'
or 'en-US')
or 'en-US').
data:
type: object
description: |-
@ -201,7 +222,17 @@ paths:
type: string
description: |-
Required if ``kind`` is ``http``. The URL to use to send
notifications to.
notifications to. MUST be an HTTPS URL with a path of
``/_matrix/push/v1/notify``.
example: "https://push-gateway.location.here/_matrix/push/v1/notify"
format:
type: string
description: |-
The format to send notifications in to Push Gateways if the
``kind`` is ``http``. The details about what fields the
homeserver should send to the push gateway are defined in the
`Push Gateway Specification`_. Currently the only format
available is 'event_id_only'.
append:
type: boolean
description: |-
@ -216,23 +247,22 @@ paths:
200:
description: The pusher was set.
examples:
application/json: |-
{}
application/json: {}
schema:
type: object # empty json object
type: object
description: An empty object.
400:
description: One or more of the pusher values were invalid.
examples:
application/json: |-
{
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
application/json: {
"error": "Missing parameters: lang, data",
"errcode": "M_MISSING_PARAM"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications

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

@ -35,6 +35,7 @@ paths:
the rulesets by suffixing a ``scope`` to this path e.g.
``/pushrules/global/``. This will return a subset of this data under the
specified key e.g. the ``global`` key.
operationId: getPushRules
security:
- accessToken: []
responses:
@ -52,8 +53,7 @@ paths:
"$ref": "definitions/push_ruleset.yaml"
]
examples:
application/json: |-
{
application/json: {
"global": {
"content": [
{
@ -248,6 +248,7 @@ paths:
summary: Retrieve a push rule.
description: |-
Retrieve a single specified push rule.
operationId: getPushRule
security:
- accessToken: []
parameters:
@ -279,8 +280,7 @@ paths:
The specific push rule. This will also include keys specific to the
rule itself such as the rule's ``actions`` and ``conditions`` if set.
examples:
application/json: |-
{
application/json: {
"actions": [
"dont_notify"
],
@ -301,6 +301,7 @@ paths:
summary: Delete a push rule.
description: |-
This endpoint removes the push rule defined in the path.
operationId: deletePushRule
security:
- accessToken: []
parameters:
@ -330,8 +331,8 @@ paths:
200:
description: The push rule was deleted.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
tags:
@ -342,6 +343,9 @@ paths:
This endpoint allows the creation, modification and deletion of pushers
for this user ID. The behaviour of this endpoint varies depending on the
values in the JSON body.
When creating push rules, they MUST be enabled by default.
operationId: setPushRule
security:
- accessToken: []
parameters:
@ -393,8 +397,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"pattern": "cake*lie",
"actions": ["notify"]
}
@ -423,26 +426,25 @@ paths:
required: ["actions"]
responses:
200:
description: The pusher was set.
description: The push rule was created/updated.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
400:
description: There was a problem configuring this push rule.
examples:
application/json: |-
{
application/json: {
"error": "before/after rule not found: someRuleId",
"errcode": "M_UNKNOWN"
}
schema:
type: object
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Push notifications
"/pushrules/{scope}/{kind}/{ruleId}/enabled":
@ -450,6 +452,7 @@ paths:
summary: "Get whether a push rule is enabled"
description:
This endpoint gets whether the specified push rule is enabled.
operationId: isPushRuleEnabled
security:
- accessToken: []
parameters:
@ -480,8 +483,7 @@ paths:
200:
description: Whether the push rule is enabled.
examples:
application/json: |-
{
application/json: {
"enabled": true
}
schema:
@ -495,6 +497,7 @@ paths:
summary: "Enable or disable a push rule."
description: |-
This endpoint allows clients to enable or disable the specified push rule.
operationId: setPushRuleEnabled
security:
- accessToken: []
parameters:
@ -532,16 +535,15 @@ paths:
type: boolean
description: Whether the push rule is enabled or not.
required: ["enabled"]
example: |-
{
example: {
"enabled": true
}
responses:
200:
description: The push rule was enabled or disabled.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
tags:
@ -551,6 +553,7 @@ paths:
summary: "The actions for a push rule"
description:
This endpoint get the actions for the specified push rule.
operationId: getPushRuleActions
security:
- accessToken: []
parameters:
@ -581,8 +584,7 @@ paths:
200:
description: The actions for this push rule.
examples:
application/json: |-
{
application/json: {
"actions": ["notify"]
}
schema:
@ -599,6 +601,7 @@ paths:
description: |-
This endpoint allows clients to change the actions of a push rule.
This can be used to change the actions of builtin rules.
operationId: setPushRuleActions
security:
- accessToken: []
parameters:
@ -640,16 +643,15 @@ paths:
enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
# TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
required: ["actions"]
example: |-
{
example: {
"actions": ["notify"]
}
responses:
200:
description: The actions for the push rule were set.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
tags:

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

@ -33,6 +33,7 @@ paths:
description: |-
This API updates the marker for the given receipt type to the event ID
specified.
operationId: postReceipt
security:
- accessToken: []
parameters:
@ -62,19 +63,19 @@ paths:
server will automatically set the ``ts`` field.
schema:
type: object
example: |-
{}
example: {
}
responses:
200:
description: The receipt was sent.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

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

@ -39,6 +39,7 @@ paths:
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
redact events there.
operationId: redactEvent
security:
- accessToken: []
parameters:
@ -66,8 +67,7 @@ paths:
name: body
schema:
type: object
example: |-
{
example: {
"reason": "Indecent material"
}
properties:
@ -78,9 +78,8 @@ paths:
200:
description: "An ID for the redaction event."
examples:
application/json: |-
{
"event_id": "YUwQidLecu"
application/json: {
"event_id": "$YUwQidLecu:example.com"
}
schema:
type: object

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

@ -45,10 +45,21 @@ paths:
If the client does not supply a ``device_id``, the server must
auto-generate one.
The server SHOULD register an account with a User ID based on the
``username`` provided, if any. Note that the grammar of Matrix User ID
localparts is restricted, so the server MUST either map the provided
``username`` onto a ``user_id`` in a logical manner, or reject
``username``\s which do not comply to the grammar, with
``M_INVALID_USERNAME``.
Matrix clients MUST NOT assume that localpart of the registered
``user_id`` matches the provided ``username``.
The returned access token must be associated with the ``device_id``
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`_.
operationId: register
parameters:
- in: query
name: kind
@ -86,7 +97,7 @@ paths:
username:
type: string
description: |-
The local part of the desired Matrix ID. If omitted,
The basis for the localpart of the desired Matrix ID. If omitted,
the homeserver MUST generate a Matrix ID local part.
example: cheeky_monkey
password:
@ -110,11 +121,9 @@ paths:
200:
description: The account has been registered.
examples:
application/json: |-
{
application/json: {
"user_id": "@cheeky_monkey:matrix.org",
"access_token": "abc123",
"home_server": "matrix.org",
"device_id": "GHTYAJCE"
}
schema:
@ -122,7 +131,11 @@ paths:
properties:
user_id:
type: string
description: The fully-qualified Matrix ID that has been registered.
description: |-
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>`_.
access_token:
type: string
description: |-
@ -130,7 +143,13 @@ paths:
This access token can then be used to authorize other requests.
home_server:
type: string
description: The hostname of the homeserver on which the account has been registered.
description: |-
The server_name of the homeserver on which the account has
been registered.
**Deprecated**. Clients should extract the server_name from
``user_id`` (by splitting at the first colon) if they require
it. Note also that ``homeserver`` is not spelt this way.
device_id:
type: string
description: |-
@ -154,11 +173,12 @@ paths:
them after authentication is completed if, for example, the requested user ID
was registered whilst the client was performing authentication.
examples:
application/json: |-
{
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
401:
description: |-
The homeserver requires additional authentication information.
@ -167,7 +187,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/email/requestToken":
@ -176,10 +196,9 @@ paths:
description: |-
Proxies the identity server API ``validate/email/requestToken``, but
first checks that the given email address is not already associated
with an account on this Home Server. Note that, for consistency,
this API takes JSON objects, though the Identity Server API takes
``x-www-form-urlencoded`` parameters. See the Identity Server API for
with an account on this Home Server. See the Identity Server API for
further information.
operationId: requestTokenToRegisterEmail
parameters:
- in: body
name: body
@ -199,9 +218,9 @@ paths:
description: The email address
example: "example@example.com"
send_attempt:
type: number
type: integer
description: Used to distinguish protocol level retries from requests to re-send the email.
example: "1"
example: 1
required: ["client_secret", "email", "send_attempt"]
responses:
200:
@ -210,7 +229,7 @@ paths:
Note that this may be an email containing the validation token or it may be informing
the user of an error.
examples:
application/json: "{}"
application/json: {}
schema:
type: object
400:
@ -225,13 +244,77 @@ paths:
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
that is not trusted by this Home Server.
examples:
application/json: |-
{
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/register/msisdn/requestToken":
post:
summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
description: |-
Proxies the identity server API ``validate/msisdn/requestToken``, but
first checks that the given phone number is not already associated
with an account on this Home Server. See the Identity Server API for
further information.
operationId: requestTokenToRegisterMSISDN
parameters:
- in: body
name: body
schema:
type: object
properties:
id_server:
type: string
description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default.
example: "id.matrix.org"
client_secret:
type: string
description: Client-generated secret string used to protect this session.
example: "this_is_my_secret_string"
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.
phone_number:
type: string
description: The phone number.
example: "example@example.com"
send_attempt:
type: integer
description: Used to distinguish protocol level retries from requests to re-send the SMS message.
example: 1
required: ["client_secret", "country", "phone_number", "send_attempt"]
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.
examples:
application/json: {}
schema:
type: object
400:
description: |-
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
However, if the home server has the ability to send SMS message, it is recommended that the server
instead send an SMS message to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given phone number
has an account on the Home Server in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
that is not trusted by this Home Server.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
"error": "The specified address is already in use"
}
schema:
"$ref": "definitions/errors/error.yaml"
"/account/password":
post:
summary: "Changes a user's password."
@ -247,6 +330,7 @@ paths:
valid access token is provided.
security:
- accessToken: []
operationId: changePassword
parameters:
- in: body
name: body
@ -266,7 +350,7 @@ paths:
200:
description: The password has been changed.
examples:
application/json: "{}"
application/json: {}
schema:
type: object
401:
@ -277,7 +361,7 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/account/password/email/requestToken":
@ -298,9 +382,32 @@ paths:
.. |/register/email/requestToken| replace:: ``/register/email/requestToken``
.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordEmail
responses:
200:
description: An email was sent to the given address
"/account/password/msisdn/requestToken":
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 server API ``validate/msisdn/requestToken``, but
first checks that the given phone number **is** associated with an account
on this Home Server. 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 email address 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.
.. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
operationId: requestTokenToResetPasswordMSISDN
responses:
200:
description: An SMS message was sent to the given phone number.
"/account/deactivate":
post:
summary: "Deactivate a user's account."
@ -317,6 +424,7 @@ paths:
valid access token is provided.
security:
- accessToken: []
operationId: deactivateAccount
parameters:
- in: body
name: body
@ -331,7 +439,7 @@ paths:
200:
description: The account has been deactivated.
examples:
application/json: "{}"
application/json: {}
schema:
type: object
401:
@ -342,6 +450,68 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data
"/register/available":
get:
summary: Checks to see if a username is available on the server.
description: |-
Checks to see if a username is available, and valid, for the server.
The server should check to ensure that, at the time of the request, the
username requested is available for use. This includes verifying that an
application service has not claimed the username and that the username
fits the server's desired requirements (for example, a server could dictate
that it does not permit usernames with underscores).
Matrix clients may wish to use this API prior to attempting registration,
however the clients must also be aware that using this API does not normally
reserve the username. This can mean that the username becomes unavailable
between checking its availability and attempting to register it.
operationId: checkUsernameAvailability
parameters:
- in: query
name: username
type: string
x-example: my_cool_localpart
required: true
default: my_cool_localpart
description: The username to check the availability of.
responses:
200:
description: The username is available
examples:
application/json: {
"available": true
}
schema:
type: object
properties:
available:
type: boolean
description: |-
A flag to indicate that the username is available. This should always
be ``true`` when the server replies with 200 OK.
400:
description: |-
Part of the request was invalid or the username is not available. This may
include one of the following error codes:
* ``M_USER_IN_USE`` : The desired username is already taken.
* ``M_INVALID_USERNAME`` : The desired username is not a valid user name.
* ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace
claimed by an application service.
examples:
application/json: {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

78
api/client-server/report_content.yaml Normal file
View file

@ -0,0 +1,78 @@
# Copyright 2018 Travis Ralston
#
# 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 Report Content 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:
"/rooms/{roomId}/report/{eventId}":
post:
summary: Reports an event as inappropriate.
description: |-
Reports an event as inappropriate to the server, which may then notify
the appropriate people.
operationId: reportContent
parameters:
- in: path
type: string
name: roomId
description: The room in which the event being reported is located.
required: true
x-example: "!637q39766251:example.com"
- in: path
type: string
name: eventId
description: The event to report.
required: true
x-example: "$something:domain.com"
- in: body
name: body
schema:
type: object
example: {
"score": -100,
"reason": "this makes me sad"
}
required: ['score', 'reason']
properties:
score:
type: integer
description: |-
The score to rate this content as where -100 is most offensive
and 0 is inoffensive.
reason:
type: string
description: The reason the content is being reported. May be blank.
security:
- accessToken: []
responses:
200:
description: The event has been reported successfully.
schema:
type: object
examples:
application/json: {}
tags:
- Reporting content

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

@ -24,6 +24,7 @@ paths:
direct replacement; the relevant information is returned by the
|/sync|_ API. See the `migration guide
<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.
operationId: roomInitialSync
security:
- accessToken: []
parameters:
@ -37,8 +38,7 @@ paths:
200:
description: The current state of the room
examples:
application/json: |-
{
application/json: {
"membership": "join",
"messages": {
"chunk": [

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

@ -38,6 +38,7 @@ 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: sendMessage
security:
- accessToken: []
parameters:
@ -66,8 +67,7 @@ paths:
name: body
schema:
type: object
example: |-
{
example: {
"msgtype": "m.text",
"body": "hello"
}
@ -75,9 +75,8 @@ paths:
200:
description: "An ID for the sent event."
examples:
application/json: |-
{
"event_id": "YUwRidLecu"
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
schema:
type: object

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

@ -42,6 +42,7 @@ 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: setRoomStateWithKey
security:
- accessToken: []
parameters:
@ -56,28 +57,28 @@ paths:
name: eventType
description: The type of event to send.
required: true
x-example: "m.room.name"
x-example: "m.room.member"
- in: path
type: string
name: stateKey
description: The state_key for the state to send. Defaults to the empty string.
required: true
x-example: ""
x-example: "@alice:example.com"
- in: body
name: body
schema:
type: object
example: |-
{
"name": "New name for the room"
example: {
"membership": "join",
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: |-
{
"event_id": "YUwRidLecu"
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
schema:
type: object
@ -104,6 +105,7 @@ 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:
@ -123,17 +125,15 @@ paths:
name: body
schema:
type: object
example: |-
{
example: {
"name": "New name for the room"
}
responses:
200:
description: "An ID for the sent event."
examples:
application/json: |-
{
"event_id": "YUwRidLecu"
application/json: {
"event_id": "$YUwRidLecu:example.com"
}
schema:
type: object

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

@ -27,6 +27,49 @@ produces:
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/rooms/{roomId}/event/{eventId}":
get:
summary: Get a single event by event ID.
description: |-
Get a single event based on ``roomId/eventId``. You must have permission to
retrieve this event e.g. by being a member in the room for this event.
operationId: getOneRoomEvent
security:
- accessToken: []
parameters:
- in: path
type: string
name: roomId
description: The ID of the room the event is in.
required: true
x-example: "!asfDuShaf7Gafaw:matrix.org"
- in: path
type: string
name: eventId
description: The event ID to get.
required: true
x-example: "$asfDuShaf7Gafaw:matrix.org"
responses:
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"
}
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.
tags:
- Room participation
"/rooms/{roomId}/state/{eventType}/{stateKey}":
get:
summary: Get the state identified by the type and key.
@ -35,6 +78,7 @@ paths:
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.
operationId: getRoomStateWithKey
security:
- accessToken: []
parameters:
@ -60,8 +104,8 @@ paths:
200:
description: The content of the state event.
examples:
application/json: |-
{"name": "Example room name"}
application/json: {
"name": "Example room name"}
schema:
type: object
404:
@ -82,6 +126,7 @@ paths:
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:
@ -101,8 +146,8 @@ paths:
200:
description: The content of the state event.
examples:
application/json: |-
{"name": "Example room name"}
application/json: {
"name": "Example room name"}
schema:
type: object
404:
@ -118,6 +163,7 @@ paths:
summary: Get all state events in the current state of a room.
description: |-
Get the state events for the current state of a room.
operationId: getRoomState
security:
- accessToken: []
parameters:
@ -131,8 +177,7 @@ paths:
200:
description: The current state of the room
examples:
application/json: |-
[
application/json: [
{
"age": 7148266897,
"content": {
@ -235,6 +280,7 @@ paths:
summary: Get the m.room.member events for the room.
description:
Get the list of members for this room.
operationId: getMembersByRoom
parameters:
- in: path
type: string
@ -242,6 +288,8 @@ paths:
description: The room to get the member events for.
required: true
x-example: "!636q39766251:example.com"
security:
- accessToken: []
responses:
200:
description: |-
@ -249,8 +297,7 @@ paths:
this will be the current members of the room. If you have left the
room then this will be the members of the room when you left.
examples:
application/json: |-
{
application/json: {
"chunk": [
{
"age": 6547561012,
@ -299,3 +346,53 @@ paths:
member of the room.
tags:
- Room participation
"/rooms/{roomId}/joined_members":
get:
summary: Gets the list of currently joined users and their profile data.
description:
This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.
operationId: getJoinedMembersByRoom
parameters:
- in: path
type: string
name: roomId
description: The room to get the members of.
required: true
x-example: "!636q39766251:example.com"
security:
- accessToken: []
responses:
200:
description: |-
A map of MXID to room member objects.
examples:
application/json: {
"joined": {
"@bar:example.com": {
"display_name": "Bar",
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
}
}
}
schema:
type: object
properties:
joined:
additionalProperties:
title: RoomMember
type: object
properties:
display_name:
type: string
description: The display name of the user this object is representing.
avatar_url:
type: string
description: The mxc avatar url of the user this object is representing.
description: A map from user ID to a RoomMember object.
type: object
403:
description: >
You aren't a member of the room.
tags:
- Room participation

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

@ -32,6 +32,7 @@ paths:
summary: Perform a server-side search.
description: |-
Performs a full text search across different categories.
operationId: search
security:
- accessToken: []
parameters:
@ -40,29 +41,28 @@ paths:
type: string
description: |-
The point to return events from. If given, this should be a
`next_batch` result from a previous call to this endpoint.
``next_batch`` result from a previous call to this endpoint.
x-example: "YWxsCgpOb25lLDM1ODcwOA"
- in: body
name: body
schema:
type: object
example: |-
{
example: {
"search_categories": {
"room_events": {
"keys": [
"content.body"
],
"search_term": "martians and men"
}
},
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
"search_term": "martians and men",
"order_by": "recent",
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
}
]
}
}
}
properties:
@ -74,7 +74,7 @@ paths:
properties:
room_events:
type: object
title: "Room Events"
title: Room Events Criteria
description: Mapping of category name to search criteria.
properties:
search_term:
@ -89,15 +89,22 @@ paths:
filter:
type: object
title: Filter
# Within the C-S spec document, `filter`_ is picked up
# as a link to the filtering section. In OpenAPI 3.0,
# we could use the link feature, but we're still on 2.0
# for now :/
description: |-
This takes a `filter <https://matrix.org/docs/spec/%CLIENT_RELEASE_LABEL%/client_server.html#filtering>`_.
This takes a `filter`_.
$ref: "definitions/room_event_filter.yaml"
order_by:
title: "Ordering"
type: string
enum: ["recent", "rank"]
description: "The order in which to search for results."
description: |-
The order in which to search for results.
By default, this is ``"rank"``.
event_context:
title: "Event Context"
title: Include Event Context
type: object
description: |-
Configures whether any context for the events
@ -108,13 +115,13 @@ paths:
title: "Before limit"
description: |-
How many events before the result are
returned.
returned. By default, this is ``5``.
after_limit:
type: integer
title: "After limit"
description: |-
How many events after the result are
returned.
returned. By default, this is ``5``.
include_profile:
type: boolean
title: "Return profile information"
@ -122,6 +129,7 @@ paths:
Requests that the server returns the
historic profile information for the users
that sent the events that were returned.
By default, this is ``false``.
include_state:
type: boolean
title: Include current state
@ -162,18 +170,24 @@ paths:
properties:
search_categories:
type: object
title: Categories
title: Result Categories
description: Describes which categories to search in and
their criteria.
properties:
room_events:
type: object
title: Room Event Results
title: Result Room Events
description: Mapping of category name to search criteria.
properties:
count:
type: number
type: integer
description: An approximate count of the total number of results found.
highlights:
type: array
title: Highlights
description: List of words which should be highlighted, useful for stemming which may change the query terms.
items:
type: string
results:
type: array
title: Results
@ -214,6 +228,9 @@ paths:
description: |-
The historic profile information of the
users that sent the events returned.
The ``string`` key is the user ID for which
the profile belongs to.
additionalProperties:
type: object
title: User Profile
@ -247,15 +264,24 @@ paths:
The current state for every room in the results.
This is included if the request had the
``include_state`` key set with a value of ``true``.
The ``string`` key is the room ID for which the ``State
Event`` array belongs to.
additionalProperties:
type: array
title: Room State
items:
type: object
"$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
groups:
type: object
title: Groups
description: Any groups that were requested.
description: |-
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:
a room's ID or a user's ID).
additionalProperties:
type: object
title: Group Key
@ -297,8 +323,7 @@ paths:
the next call. If this field is absent, there are no
more results.
examples:
application/json: |-
{
application/json: {
"search_categories": {
"room_events": {
"groups": {
@ -312,6 +337,10 @@ paths:
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"count": 1224,
"results": [
@ -339,6 +368,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Search

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

@ -34,6 +34,7 @@ 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.
operationId: sync
security:
- accessToken: []
parameters:
@ -88,8 +89,12 @@ paths:
name: timeout
type: integer
description: |-
The maximum time to poll in milliseconds before returning this
request.
The maximum time to wait, in milliseconds, before returning this
request. If no events (or other data) become available before this
time elapses, the server will return a response with empty fields.
By default, this is ``0``, so the server will return immediately
even if the response is empty.
x-example: 30000
responses:
200:
@ -222,6 +227,14 @@ paths:
room up to the point when the user left.
allOf:
- $ref: "definitions/timeline_batch.yaml"
account_data:
title: Account Data
type: object
description: |-
The private data that this user has attached to
this room.
allOf:
- $ref: "definitions/event_batch.yaml"
presence:
title: Presence
type: object
@ -242,9 +255,22 @@ paths:
description: |-
Information on the send-to-device messages for the client
device, as defined in |send_to_device_sync|_.
device_lists:
title: DeviceLists
type: object
description: |-
Information on end-to-end device updates, as specified in
|device_lists_sync|_.
device_one_time_keys_count:
title: One-time keys count
type: object
additionalProperties:
type: integer
description: |-
Information on end-to-end encryption keys, as specified
in |device_lists_sync|_.
examples:
application/json: |-
{
application/json: {
"next_batch": "s72595_4483_1934",
"presence": {
"events": [

24
api/client-server/tags.yaml
View file

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -32,6 +33,7 @@ paths:
summary: List the tags for a room.
description: |-
List the tags set by a user on a room.
operationId: getRoomTags
security:
- accessToken: []
parameters:
@ -61,11 +63,11 @@ paths:
title: Tags
type: object
examples:
application/json: |-
{
application/json: {
"tags": {
"work": {"order": "1"},
"pinned": {}
"m.favourite": {},
"u.Work": {"order": "1"},
"u.Customers": {}
}
}
tags:
@ -75,6 +77,7 @@ paths:
summary: Add a tag to a room.
description: |-
Add a tag to the room.
operationId: setRoomTag
security:
- accessToken: []
parameters:
@ -107,8 +110,8 @@ paths:
Extra data for the tag, e.g. ordering.
schema:
type: object
example: |-
{"order": "1"}
example: {
"order": "1"}
responses:
200:
description:
@ -116,14 +119,15 @@ paths:
schema:
type: object
examples:
application/json: |-
{}
application/json: {
}
tags:
- User data
delete:
summary: Remove a tag from the room.
description: |-
Remove a tag from the room.
operationId: deleteRoomTag
security:
- accessToken: []
parameters:
@ -156,7 +160,7 @@ paths:
schema:
type: object
examples:
application/json: |-
{}
application/json: {
}
tags:
- User data

208
api/client-server/third_party_lookup.yaml Normal file
View file

@ -0,0 +1,208 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server Third Party Lookup 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:
"/thirdparty/protocols":
get:
summary: Retrieve metadata about all protocols that a homeserver supports.
description: |-
Fetches the overall metadata about protocols supported by the
homeserver. Includes both the available protocols and all fields
required for queries against each protocol.
operationId: getProtocols
security:
- accessToken: []
responses:
200:
description: The protocols supported by the homeserver.
schema:
$ref: ../application-service/definitions/protocol_metadata.yaml
"/thirdparty/protocol/{protocol}":
get:
summary: Retrieve metadata about a specific protocol that the homeserver supports.
description: |-
Fetches the metadata from the homeserver about a particular third party protocol.
operationId: getProtocolMetadata
security:
- accessToken: []
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: "irc"
responses:
200:
description: The protocol was found and metadata returned.
schema:
$ref: ../application-service/definitions/protocol.yaml
404:
description: The protocol is unknown.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/location/{protocol}":
get:
summary: Retrieve Matrix-side portals rooms leading to a third party location.
description: |-
Requesting this endpoint with a valid protocol name results in a list
of successful mapping results in a JSON array. Each result contains
objects to represent the Matrix room or rooms that represent a portal
to this third party network. Each has the Matrix room alias string,
an identifier for the particular third party network protocol, and an
object containing the network-specific fields that comprise this
identifier. It should attempt to canonicalise the identifier as much
as reasonably possible given the network type.
operationId: queryLocationByProtocol
security:
- accessToken: []
parameters:
- in: path
name: protocol
type: string
description: The protocol used to communicate to the third party network.
required: true
x-example: irc
- in: query
name: searchFields
type: string
description: |-
One or more custom fields to help identify the third party
location.
responses:
200:
description: At least one portal room was found.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
description: No portal rooms were found.
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/user/{protocol}":
get:
summary: Retrieve the Matrix User ID of a corresponding third party user.
description: |-
Retrieve a Matrix User ID linked to a user on the third party service, given
a set of user parameters.
operationId: queryUserByProtocol
security:
- accessToken: []
parameters:
- in: path
name: protocol
type: string
description: |-
The name of the protocol.
required: true
x-example: irc
- in: query
name: fields...
type: string
description: |-
One or more custom fields that are passed to the AS to help identify the user.
responses:
200:
description: The Matrix User IDs found with the given parameters.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/location":
get:
summary: Reverse-lookup third party locations given a Matrix room alias.
description: |-
Retrieve an array of third party network locations from a Matrix room
alias.
operationId: queryLocationByAlias
security:
- accessToken: []
parameters:
- in: query
name: alias
type: string
description: The Matrix room alias to look up.
required: true
x-example: "#matrix:matrix.org"
responses:
200:
description: |-
All found third party locations.
schema:
$ref: ../application-service/definitions/location_batch.yaml
404:
description: The Matrix room alias was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml
"/thirdparty/user":
get:
summary: Reverse-lookup third party users given a Matrix User ID.
description: |-
Retrieve an array of third party users from a Matrix User ID.
operationId: queryUserByID
security:
- accessToken: []
parameters:
- in: query
name: userid
type: string
description: The Matrix User ID to look up.
required: true
x-example: "@bob:matrix.org"
responses:
200:
description: |-
An array of third party users.
schema:
$ref: ../application-service/definitions/user_batch.yaml
404:
description: The Matrix User ID was not found
examples:
application/json: {
"errcode": "M_NOT_FOUND"
}
schema:
$ref: definitions/errors/error.yaml

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

@ -75,6 +75,7 @@ paths:
append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_
operationId: inviteBy3PID
security:
- accessToken: []
parameters:
@ -89,8 +90,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"id_server": "matrix.org",
"medium": "email",
"address": "cheeky@monkey.com"
@ -111,8 +111,8 @@ paths:
200:
description: The user has been invited to join the room.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object
403:
@ -124,11 +124,13 @@ paths:
- The inviter is not currently in the room.
- The inviter's power level is insufficient to invite users to the room.
examples:
application/json: |-
{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
application/json: {
"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room membership

5
api/client-server/to_device.yaml
View file

@ -34,6 +34,7 @@ paths:
description: |-
This endpoint is used to send send-to-device events to a set of
client devices.
operationId: sendToDevice
security:
- accessToken: []
parameters:
@ -83,7 +84,7 @@ paths:
description:
The message was successfully sent.
examples:
application/json: |-
{}
application/json: {
}
tags:
- Send-to-Device messaging

10
api/client-server/typing.yaml
View file

@ -35,6 +35,7 @@ paths:
milliseconds where N is the value specified in the ``timeout`` key.
Alternatively, if ``typing`` is ``false``, it tells the server that the
user has stopped typing.
operationId: setTyping
security:
- accessToken: []
parameters:
@ -56,8 +57,7 @@ paths:
required: true
schema:
type: object
example: |-
{
example: {
"typing": true,
"timeout": 30000
}
@ -75,13 +75,13 @@ paths:
200:
description: The new typing state was set.
examples:
application/json: |-
{}
application/json: {
}
schema:
type: object # empty json object
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- Room participation

100
api/client-server/users.yaml Normal file
View file

@ -0,0 +1,100 @@
# Copyright 2017 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Client-Server User Directory 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:
"/user_directory/search":
post:
summary: Searches the user directory.
description: |-
This API performs a server-side search over all users registered on the server.
It searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.
operationId: searchUserDirectory
security:
- accessToken: []
parameters:
- in: body
name: body
schema:
type: object
properties:
search_term:
type: string
description: The term to search for
example: "foo"
limit:
type: integer
description: The maximum number of results to return (Defaults to 10).
example: 10
required: ["search_term"]
responses:
200:
description: The results of the search.
examples:
application/json: {
"results": [
{
"user_id": "@foo:bar.com",
"display_name": "Foo",
"avatar_url": "mxc://bar.com/foo"
}
],
"limited": false
}
schema:
type: object
required: ["results", "limited"]
properties:
results:
type: array
description: Ordered by rank and then whether or not profile info is available.
items:
title: User
type: object
required: ["user_id"]
properties:
user_id:
type: string
example: "@foo:bar.com"
description: The user's matrix user ID.
display_name:
type: string
example: "Foo"
description: The display name of the user, if one exists.
avatar_url:
type: string
example: "mxc://bar.com/foo"
description: The avatar url, as an MXC, if one exists.
limited:
type: boolean
description: Indicates if the result list has been truncated by the limit.
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

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

@ -33,12 +33,12 @@ paths:
Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
operationId: getVersions
responses:
200:
description: The versions supported by the server.
examples:
application/json: |-
{
application/json: {
"versions": ["r0.0.1"]
}
schema:

6
api/client-server/voip.yaml
View file

@ -33,14 +33,14 @@ paths:
description: |-
This API provides credentials for the client to use when initiating
calls.
operationId: getTurnServer
security:
- accessToken: []
responses:
200:
description: The TURN server credentials.
examples:
application/json: |-
{
application/json: {
"username":"1443779631:@user:example.com",
"password":"JlKfBy1QwLrO20385QyAtEyIv0=",
"uris":[
@ -73,6 +73,6 @@ paths:
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/error.yaml"
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- VOIP

84
api/client-server/whoami.yaml Normal file
View file

@ -0,0 +1,84 @@
# Copyright 2017 Travis Ralston
#
# 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 Account Identification API"
version: "1.0.0"
host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/account/whoami":
get:
summary: Gets information about the owner of an access token.
description: |-
Gets information about the owner of a given access token.
Note that, as with the rest of the Client-Server API,
Application Services may masquerade as users within their
namespace by giving a ``user_id`` query parameter. In this
situation, the server should verify that the given ``user_id``
is registered by the appservice, and return it in the response
body.
operationId: getTokenOwner
security:
- accessToken: []
parameters: []
responses:
200:
description:
The token belongs to a known user.
examples:
application/json: {
"user_id": "@joe:example.org"
}
schema:
type: object
required: ["user_id"]
properties:
user_id:
type: string
description: The user id that owns the access token.
401:
description:
The token is not recognised
examples:
application/json: {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token."
}
schema:
"$ref": "definitions/errors/error.yaml"
403:
description:
The appservice cannot masquerade as the user or has not registered them.
examples:
application/json: {
"errcode": "M_FORBIDDEN",
"error": "Application service has not registered this user."
}
schema:
"$ref": "definitions/errors/error.yaml"
429:
description: This request was rate-limited.
schema:
"$ref": "definitions/errors/rate_limited.yaml"
tags:
- User data

179
api/identity/associations.yaml Normal file
View file

@ -0,0 +1,179 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Establishing Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
paths:
"/3pid/getValidated3pid":
get:
summary: Check whether ownership of a 3pid was validated.
description: A client can check whether ownership of a 3pid was validated
operationId: getValidated3pid
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 indicating the time that the 3pid was validated.
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"
}
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"
}
"/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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: bind
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 services which show that the association should be trusted, if you trust the verifying identity services.
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"
}
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"
}

197
api/identity/email_associations.yaml Normal file
View file

@ -0,0 +1,197 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Email Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
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 service will send an email containing a token. If that
token is presented to the identity service 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 Home Servers 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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailRequestToken
parameters:
- in: body
name: body
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"email": "foo@example.com",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt
email:
type: string
description: The email address to validate.
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an email if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``email`` + ``client_secret`` pair. This is to avoid
repeatedly sending the same email in the case of request
retries between the POSTing user and the identity
service. The client should increment this value if they
desire a new email (e.g. a reminder) to be sent.
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
required: ["client_secret", "email"]
responses:
200:
description:
Session created.
examples:
application/json: {
"sid": "1234"
}
schema:
type: object
properties:
sid:
type: string
description: The session ID.
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.
"/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.
Note: for backwards compatibility with older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: emailSubmitTokenPost
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.
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: emailSubmitTokenGet
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.

90
api/identity/invitation_signing.yaml Normal file
View file

@ -0,0 +1,90 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Ephemeral Invitation Signing API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
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: blindlySignStuff
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: 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 signedjson 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.
token:
type: string
description: The token for the invitation.
examples:
application/json: {
"mxid": "@foo:bar.com",
"sender": "@baz:bar.com",
"signatures": {
"my.id.server": {
"ed25519:0": "def987"
}
},
"token": "abc123"
}
404:
description: Token was not found.
example: {
"errcode": "M_UNRECOGNIZED",
"error": "Didn't recognize token"
}

66
api/identity/lookup.yaml
View file

@ -1,4 +1,6 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -27,26 +29,26 @@ paths:
get:
summary: Look up the Matrix user ID for a 3pid.
description: Look up the Matrix user ID for a 3pid.
operationId: lookupUser
parameters:
- in: query
type: string
name: medium
required: true
description: The literal string "email".
description: The medium type of the 3pid. See the `3PID Types`_ Appendix.
x-example: "email"
- in: query
type: string
name: address
required: true
description: The email address being looked up.
description: The address of the 3pid being looked up. See the `3PID Types`_ Appendix.
x-example: "louise@bobs.burgers"
responses:
200:
description:
The association for that 3pid, or the empty object if no association is known.
examples:
application/json: |-
{
application/json: {
"address": "louise@bobs.burgers",
"medium": "email",
"mxid": "@ears:matrix.org",
@ -83,4 +85,58 @@ paths:
description: The unix timestamp at which the association was verified.
signatures:
type: object
description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service.
description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services.
"/bulk_lookup":
post:
summary: Lookup Matrix user IDs for a list of 3pids.
description: Lookup Matrix user IDs for a list of 3pids.
operationId: lookupUsers
parameters:
- in: body
name: body
schema:
type: object
example: {
"threepids":
[
["email","user@example.org"],
["msisdn", "123456789"],
["email","user2@example.org"]
]
}
properties:
threepids:
type: array
items:
type: array
title: 3PID mappings
items:
type: string
title: 3PID medium or address
description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position.
required:
- "threepids"
responses:
200:
description: A list of known 3PID mappings for the supplied 3PIDs.
examples:
application/json: {
"threepids": [
["email","user@example.org", "@bla:example.org"],
["msisdn", "123456789", "@blah2:example.com"]
]
}
schema:
type: object
properties:
threepids:
type: array
items:
type: array
title: 3PID mappings
items:
type: string
title: 3PID medium or address or the Matrix ID
description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position.
required:
- "threepids"

203
api/identity/phone_associations.yaml Normal file
View file

@ -0,0 +1,203 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Phone Number Associations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
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 service will send an SMS message containing a token. If
that token is presented to the identity service 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 Home Servers 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 older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnRequestToken
parameters:
- in: body
name: body
schema:
type: object
example: {
"client_secret": "monkeys_are_GREAT",
"country": "GB",
"phone_number": "07700900001",
"send_attempt": 1
}
properties:
client_secret:
type: string
description: A unique string used to identify the validation attempt.
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.
phone_number:
type: string
description: The phone number to validate.
send_attempt:
type: integer
description: |-
Optional. If specified, the server will only send an SMS if
the ``send_attempt`` is a number greater than the most recent
one which it has seen (or if it has never seen one), scoped
to that ``country`` + ``phone_number`` + ``client_secret``
triple. This is to avoid repeatedly sending the same SMS in
the case of request retries between the POSTing user and the
identity service. The client should increment this value if
they desire a new SMS (e.g. a reminder) to be sent.
next_link:
type: string
description: |-
Optional. When the validation is completed, the identity
service will redirect the user to this URL.
required: ["client_secret", "country", "phone_number"]
responses:
200:
description:
Session created.
examples:
application/json: {
"sid": "1234"
}
schema:
type: object
properties:
sid:
type: string
description: The session ID.
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.
"/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.
Note: for backwards compatibility with older versions of this
specification, the parameters may also be specified as
``application/x-form-www-urlencoded`` data. However, this usage is
deprecated.
operationId: msisdnSubmitTokenPost
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.
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: msisdnSubmitTokenGet
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.

44
api/identity/ping.yaml Normal file
View file

@ -0,0 +1,44 @@
# Copyright 2018 Kamax Sàrl
#
# 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-Identity Versions API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
basePath: /_matrix/identity
produces:
- application/json
paths:
"/api/v1":
get:
summary: Checks that an Identity server is available at this API endpopint.
description: |-
Checks that an Identity server is available at this API endpopint.
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: ping
responses:
200:
description: An Identity server is ready to serve requests.
examples:
application/json: {}
schema:
type: object

12
api/identity/pubkey.yaml
View file

@ -28,6 +28,7 @@ paths:
summary: Get a public key.
description: |-
Get the public key for the passed key ID.
operationId: getPubKey
parameters:
- in: path
type: string
@ -43,8 +44,7 @@ paths:
description:
The public key exists.
examples:
application/json: |-
{
application/json: {
"public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
}
schema:
@ -57,6 +57,7 @@ paths:
summary: Check whether a long-term public key is valid.
description: |-
Check whether a long-term public key is valid.
operationId: isPubKeyValid
parameters:
- in: query
type: string
@ -70,8 +71,7 @@ paths:
description:
The validity of the public key.
examples:
application/json: |-
{
application/json: {
"valid": true
}
schema:
@ -85,6 +85,7 @@ paths:
summary: Check whether a short-term public key is valid.
description: |-
Check whether a short-term public key is valid.
operationId: isEphemeralPubKeyValid
parameters:
- in: query
type: string
@ -98,8 +99,7 @@ paths:
description:
The validity of the public key.
examples:
application/json: |-
{
application/json: {
"valid": true
}
schema:

114
api/identity/store_invite.yaml Normal file
View file

@ -0,0 +1,114 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Identity Service Store Invitations API"
version: "1.0.0"
host: localhost:8090
schemes:
- https
- http
basePath: /_matrix/identity/api/v1
produces:
- application/json
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/api/v1/pubkey/ephemeral/isvalid``.
operationId: storeInvite
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``.
address:
type: string
description: The email address of the invited user.
room_id:
type: string
description: The Matrix room ID to which the user is invited
sender:
type: string
description: The Matrix user ID of the inviting user
required: ["medium", "address", "room_id", "sender"]
responses:
200:
description: The invitation was stored.
schema:
type: object
properties:
token:
type: string
description: The generated token.
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.
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": mxid
}

45
api/openapi_extensions.md Normal file
View file

@ -0,0 +1,45 @@
# OpenAPI Extensions
For some functionality that is not directly provided by the OpenAPI v2
specification, some extensions have been added that are to be consistent
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.
## Extensible Query Parameters
<!-- TODO: Remove and change instances to 'explode' after OpenAPI/Swagger v3 update -->
If a unknown amount of query parameters can be added to a request, the `name`
must be `fields...`, with the trailing ellipses representing the possibility
of more fields.
Example:
```
- in: query
name: fields...
type: string
```
## Using oneOf to provide type alternatives
<!-- TODO: Remove this section after upgrading to OpenAPI v3 -->
`oneOf` (available in JSON Schema and Swagger/OpenAPI v3 but not in v2)
is used in cases when a simpler type specification as a list of types
doesn't work, as in the following example:
```
properties:
old: # compliant with old Swagger
type:
- string
- object # Cannot specify a schema here
new: # uses oneOf extension
oneOf:
- type: string
- type: object
title: CustomSchemaForTheWin
properties:
...
```

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

@ -1,4 +1,5 @@
# Copyright 2016 OpenMarket Ltd
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -19,7 +20,7 @@ host: localhost:8008
schemes:
- https
- http
basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
basePath: /_matrix/push/v1
consumes:
- application/json
produces:
@ -38,15 +39,15 @@ paths:
Notifications about a particular event will normally cause the user to be
alerted in some way. It is therefore necessary to perform duplicate
suppression for such notifications using the `event_id` field to avoid
suppression for such notifications using the ``event_id`` field to avoid
retries of this HTTP API causing duplicate alerts. The operation of
updating counts of unread notifications should be idempotent and
therefore do not require duplicate suppression.
Notifications are sent to the URL configured when the pusher is
created. This means that the HTTP path may be different depending on the
push gateway.
Notifications are sent to the URL configured when the pusher is created.
This means that the HTTP path may be different depending on the push
gateway.
operationId: notify
parameters:
- in: body
name: notification
@ -54,38 +55,37 @@ paths:
required: true
schema:
type: object
example: |-
{
"notification": {
"id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"content": {
"msgtype": "m.text",
"body": "I'm floating in a most peculiar way."
},
"counts": {
"unread" : 2,
"missed_calls": 1
},
"devices": [
{
"app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678,
"data" : {},
"tweaks": {
"sound": "bing"
}
example: {
"notification": {
"id": "$3957tyerfgewrf384",
"room_id": "!slw48wfj34rtnrf:example.com",
"type": "m.room.message",
"sender": "@exampleuser:matrix.org",
"sender_display_name": "Major Tom",
"room_name": "Mission Control",
"room_alias": "#exampleroom:matrix.org",
"prio": "high",
"content": {
"msgtype": "m.text",
"body": "I'm floating in a most peculiar way."
},
"counts": {
"unread" : 2,
"missed_calls": 1
},
"devices": [
{
"app_id": "org.matrix.matrixConsole.ios",
"pushkey": "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/",
"pushkey_ts": 12345678,
"data" : {},
"tweaks": {
"sound": "bing"
}
]
}
}
]
}
}
required: ["notification"]
properties:
notification:
@ -112,14 +112,10 @@ paths:
type: string
description: |-
The type of the event as in the event's ``type`` field.
Required if the notification relates to a specific
Matrix event.
sender:
type: string
description: |-
The sender of the event as in the corresponding event field.
Required if the notification relates to a specific
Matrix event.
sender_display_name:
type: string
description: |-
@ -149,15 +145,16 @@ paths:
type: object
title: EventContent
description: |-
The ``content`` field from the event, if present. If the
event had no content field, this field is omitted.
The ``content`` field from the event, if present. The pusher
may omit this if the event had no content or for any other
reason.
counts:
type: object
title: Counts
description: |-
This is a dictionary of the current number of unacknowledged
communications for the recipient user. Counts whose value is
zero are omitted.
zero should be omitted.
properties:
unread:
type: integer
@ -181,10 +178,10 @@ paths:
app_id:
type: string
description: |-
The app_id given when the pusher was created.
The ``app_id`` given when the pusher was created.
pushkey:
type: string
description: The pushkey given when the pusher was created.
description: The ``pushkey`` given when the pusher was created.
pushkey_ts:
type: integer
description: |-
@ -203,14 +200,14 @@ paths:
description: |-
A dictionary of customisations made to the way this
notification is to be presented. These are added by push rules.
required: ['app_id', 'pushkey']
responses:
200:
description: A list of rejected push keys.
examples:
application/json: |-
{
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
application/json: {
"rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
}
schema:
type: object # empty json object
properties:
@ -224,7 +221,8 @@ paths:
pushkeys and remove the associated pushers. It may not
necessarily be the notification in the request that failed:
it could be that a previous notification to the same pushkey
failed.
failed. May be empty.
items:
type: string
description: A pushkey
description: A pushkey that has been rejected.
required: ['rejected']

148
api/server-server/backfill.yaml Normal file
View file

@ -0,0 +1,148 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
swagger: '2.0'
info:
title: "Matrix Federation Events API"
version: "1.0.0"
host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
- application/json
produces:
- application/json
securityDefinitions:
$ref: definitions/security.yaml
paths:
"/backfill/{roomId}":
get:
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``.
operationId: backfillRoom
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to backfill.
required: true
x-example: "!SomeRoom:matrix.org"
- in: query
name: v
type: array
items:
type: string
description: The event IDs to backfill from.
required: true
x-example: ["$abc123:matrix.org"]
- in: query
name: limit
type: integer
description: The maximum number of PDUs to retrieve, including the given events.
required: true
x-example: 2
responses:
200:
description: |-
A transaction containing the PDUs that preceded the given event(s), including the given
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
# Override the example to show the response of the request a bit better
examples:
application/json: {
"$ref": "examples/transaction.json",
"pdus": [
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org",
"event_id": "$abc123:matrix.org"
},
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org"
},
]
}
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
description: |-
Retrieves previous events that the sender is missing. This is done by doing a breadth-first
walk of the ``prev_events`` for the ``latest_events``, ignoring any events in ``earliest_events``
and stopping at the ``limit``.
operationId: getMissingPreviousEvents
security:
- signedRequest: []
parameters:
- in: path
name: roomId
type: string
description: The room ID to search in.
required: true
x-example: "!SomeRoom:matrix.org"
- in: body
name: body
schema:
type: object
properties:
limit:
type: integer
description: The maximum number of events to retrieve. Defaults to 10.
example: 10
min_depth:
type: integer
description: The minimum depth of events to retrieve. Defaults to 0.
example: 0
earliest_events:
type: array
description: |-
The latest events that the sender already has. These are skipped when retrieving
the previous events of ``latest_events``.
items:
type: string
example: ["$missing_event:domain.com"]
latest_events:
type: array
description: The events to retrieve the previous events for.
items:
type: string
example: ["$event_that_has_the_missing_event_as_a_previous_event:domain.com"]
required: ['earliest_events', 'latest_events']
responses:
200:
description: |-
The previous events for ``latest_events``, excluding any ``earliest_events``, up to the
provided ``limit``.
schema:
type: object
properties:
events:
type: array
description: The missing events.
items:
$ref: definitions/pdu.yaml
required: ['events']
examples:
application/json: {
"events": [
{"$ref": "examples/pdu.json"}
]
}

28
api/server-server/definitions/edu.yaml Normal file
View file

@ -0,0 +1,28 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Ephemeral Data Unit
description: An ephemeral data unit.
example:
$ref: "../examples/edu.json"
properties:
edu_type:
type: string
description: The type of ephemeral message.
example: "m.presence"
content:
type: object
description: The content of the ephemeral message.
required: ['edu_type', 'content']

71
api/server-server/definitions/event-schemas/m.presence.yaml Normal file
View file

@ -0,0 +1,71 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.presence
description: |-
An EDU representing presence updates for users of the sending homeserver.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence']
description: The string ``m.presence``
example: "m.presence"
content:
type: object
description: The presence updates and requests.
title: Presence Update
properties:
push:
type: array
description: |-
A list of presence updates that the receiving server is likely
to be interested in.
items:
type: object
title: User Presence Update
properties:
user_id:
type: string
description: The user ID this presence EDU is for.
example: "@john:matrix.org"
presence:
type: enum
enum: ['offline', 'unavailable', 'online']
description: The presence of the user.
example: "online"
status_msg:
type: string
description: An optional description to accompany the presence.
example: "Making cupcakes"
last_active_ago:
type: integer
format: int64
description: |-
The number of milliseconds that have elapsed since the user
last did something.
example: 5000
currently_active:
type: boolean
description: |-
True if the user is likely to be interacting with their
client. This may be indicated by the user having a
``last_active_ago`` within the last few minutes. Defaults
to false.
example: true
required: ['user_id', 'presence', 'last_active_ago']
required: ['push']

46
api/server-server/definitions/event-schemas/m.presence_accept.yaml Normal file
View file

@ -0,0 +1,46 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.presence_accept
description: |-
An EDU representing approval for the observing user to subscribe to the
presence of the the observed user.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence_accept']
description: The string ``m.presence_accept``
example: "m.presence_accept"
content:
type: object
description: The invite information.
title: Invite Information
properties:
observed_user:
type: string
description: |-
The user ID that has approved the ``observer_user`` to
subscribe to their presence.
example: "@alice:elsewhere.com"
observer_user:
type: string
description: |-
The user ID that requested to subscribe to the presence of
the ``observed_user``.
example: "@john:matrix.org"
required: ['observer_user', 'observed_user']

55
api/server-server/definitions/event-schemas/m.presence_deny.yaml Normal file
View file

@ -0,0 +1,55 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.presence_deny
description: |-
An EDU representing a declination or revocation for the observing user
to subscribe to the presence of the observed user.
example: {
"origin": "domain.com",
"destination": "elsewhere.org",
"edu_type": "m.presence_deny",
"content": {
"observed_user": "@alice:elsewhere.org",
"observer_user": "@john:domain.com"
}
}
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence_deny']
description: The string ``m.presence_deny``
example: "m.presence_deny"
content:
type: object
description: The invite information.
title: Invite Information
properties:
observed_user:
type: string
description: |-
The user ID that has declined or revoked the ``observer_user`` from
subscribing to their presence.
example: "@alice:elsewhere.com"
observer_user:
type: string
description: |-
The user ID that requested to subscribe to the presence of
the ``observed_user``.
example: "@john:matrix.org"
required: ['observer_user', 'observed_user']

45
api/server-server/definitions/event-schemas/m.presence_invite.yaml Normal file
View file

@ -0,0 +1,45 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.presence_invite
description: |-
An EDU representing a request to subscribe to a user's presence.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.presence_invite']
description: The string ``m.presence_invite``
example: "m.presence_invite"
content:
type: object
description: The invite information.
title: Invite Information
properties:
observed_user:
type: string
description: |-
The user ID the ``observer_user`` would like to subscribe
to the presence of.
example: "@alice:elsewhere.com"
observer_user:
type: string
description: |-
The user ID that is wishing to subscribe to the presence of
the ``observed_user``.
example: "@john:matrix.org"
required: ['observer_user', 'observed_user']

82
api/server-server/definitions/event-schemas/m.receipt.yaml Normal file
View file

@ -0,0 +1,82 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.receipt
description: |-
An EDU representing receipt updates for users of the sending homeserver.
When receiving receipts, the server should only update entries that are
listed in the EDU. Receipts previously received that do not appear in the
EDU should not be removed or otherwise manipulated.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.receipt']
description: The string ``m.receipt``
example: "m.receipt"
content:
type: object
description: |-
Receipts for a particular room. The string key is the room ID for
which the receipts under it belong.
additionalProperties:
type: object
title: Room Receipts
properties:
# We strongly define the receipt type to help spec future ones later
# on. At that point, m.read can become optional (maybe).
"m.read":
type: object
description: Read receipts for users in the room.
title: User Read Receipt
properties:
event_ids:
type: array
description: |-
The extremity event IDs that the user has read up to.
minItems: 1
maxItems: 1
items:
type: string
example: ['$read_this_event:matrix.org']
data:
type: object
description: Metadata for the read receipt.
title: Read Receipt Metadata
properties:
ts:
type: integer
format: int64
description: |-
A POSIX timestamp in milliseconds for when the user read
the event specified in the read receipt.
example: 1533358089009
required: ['ts']
required: ['event_ids', 'data']
required: ['m.read']
example: {
"!some_room:domain.com": {
"m.read": {
"@john:matrix.org": {
"event_ids": ["$read_this_event:matrix.org"],
"data": {
"ts": 1533358089009
}
}
}
}
}

46
api/server-server/definitions/event-schemas/m.typing.yaml Normal file
View file

@ -0,0 +1,46 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: m.typing
description: A typing notification EDU for a user in a room.
allOf:
- $ref: ../edu.yaml
- type: object
properties:
edu_type:
type: enum
enum: ['m.typing']
description: The string ``m.typing``
example: "m.typing"
content:
type: object
description: The typing notification.
title: Typing Notification
properties:
room_id:
type: string
description: |-
The room where the user's typing status has been updated.
example: "!somewhere:matrix.org"
user_id:
type: string
description: |-
The user ID that has had their typing status changed.
example: "@john:matrix.org"
typing:
type: boolean
description: Whether the user is typing in the room or not.
example: true
required: ['room_id', 'user_id', 'typing']

87
api/server-server/definitions/invite_event.yaml Normal file
View file

@ -0,0 +1,87 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Invite Event
description: An invite event
allOf:
- $ref: "pdu.yaml"
- type: object
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
type: string
# TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite
description: |-
The matrix ID of the user who sent the original ``m.room.third_party_invite``.
example: "@someone:example.org"
origin:
type: string
description: The name of the inviting homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the inviting 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 invited member.
example: "@joe:elsewhere.com"
content:
type: object
title: Membership Event Content
description: |-
The content of the event, matching what is available in the
`Client-Server API`_. Must include a ``membership`` of ``invite``.
example: {"membership": "invite"}
properties:
membership:
type: string
description: The value ``invite``.
example: "invite"
required: ['membership']
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to be invited to the room.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key

110
api/server-server/definitions/keys.yaml Normal file
View file

@ -0,0 +1,110 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Server Keys
description: Server keys
example:
$ref: "../examples/server_key.json"
properties:
server_name:
type: string
description: DNS name of the homeserver.
required: true
example: "example.org"
verify_keys:
type: object
description: |-
Public keys of the homeserver for verifying digital signatures.
The object's key is the algorithm and version combined (``ed25519`` being the
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
example: {
"ed25519:abc123": {
"key": "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
}
}
properties:
key:
type: string
description: The `Unpadded Base64`_ encoded key.
required: true
example: "VGhpcyBzaG91bGQgYmUgYSByZWFsIGVkMjU1MTkgcGF5bG9hZA"
old_verify_keys:
type: object
description: |-
The public keys that the server used to use and when it stopped using them.
The object's key is the algorithm and version combined (``ed25519`` being the
algorithm and ``0ldK3y`` 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_]``.
additionalProperties:
type: object
title: Old Verify Key
example: {
"ed25519:0ldK3y": {
"expired_ts": 1532645052628,
"key": "VGhpcyBzaG91bGQgYmUgeW91ciBvbGQga2V5J3MgZWQyNTUxOSBwYXlsb2FkLg"
}
}
properties:
expired_ts:
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"
signatures:
type: object
description: Digital signatures for this object signed using the ``verify_keys``.
additionalProperties:
type: object
title: Signed Server
example: {
"example.org": {
"ad25519:abc123": "VGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgYSBzaWduYXR1cmU"
}
}
additionalProperties:
type: string
name: Encoded Signature Verification Key
tls_fingerprints:
type: array
description: Hashes of X.509 TLS certificates used by this server.
items:
type: object
title: TLS Fingerprint
properties:
sha256:
type: string
description: The `Unpadded Base64`_ encoded fingerprint.
example: "VGhpcyBpcyBoYXNoIHdoaWNoIHNob3VsZCBiZSBieXRlcw"
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.
example: 1052262000000

27
api/server-server/definitions/keys_query_response.yaml Normal file
View file

@ -0,0 +1,27 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
description: Server keys
example: {
"server_keys": [{
$ref: "../examples/server_key_notary_signed.json"
}]
}
properties:
server_keys:
type: array
title: Server Keys
description: The queried server's keys, signed by the notary server.
items:
$ref: "keys.yaml"

52
api/server-server/definitions/pdu.yaml Normal file
View file

@ -0,0 +1,52 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Persistent Data Unit
description: A persistent data unit (event)
example:
$ref: "../examples/pdu.json"
allOf:
- $ref: "unsigned_pdu.yaml"
- type: object
properties:
hashes:
type: object
title: Event Hash
description: Hashes of the PDU, following the algorithm specified in `Signing Events`_.
example: {
"sha256": "thishashcoversallfieldsincasethisisredacted"
}
properties:
sha256:
type: string
description: The hash.
example: thishashcoversallfieldsincasthisisredacted
required: ['sha256']
signatures:
type: object
description: |-
Signatures for the PDU, following the algorithm specified in `Signing Events`_.
example: {
"example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
}
}
additionalProperties:
type: object
title: Server Signatures
additionalProperties:
type: string
required:
- hashes
- signatures

19
api/server-server/definitions/security.yaml Normal file
View file

@ -0,0 +1,19 @@
# Copyright 2018 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
signedRequest:
type: apiKey
description: |-
The ``Authorization`` header defined in the `Authentication`_ section.
name: Authorization
in: header

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