Merge branch 'master' into human-id-rules

.gitignore

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

CHANGELOG.rst

@@ -1,41 +0,0 @@
-.. This file is automatically processed by the templating system. To make it
-.. happy, you MUST use '=' as the title underline and you MUST stick the version
-.. in the title. The version MUST follow the numbering format 
-.. "v<num>.<num>.<num>" - You cannot use a-z. If the templating system fails to
-.. find the right info, it will be treated as a test failure and so will show up
-.. in Jenkins. Comments like this are ignored by both RST and the templating
-.. system. Add the newest release notes beneath this comment.
-
-Specification changes in v0.2.0 (2015-10-02)
-============================================
-
-This update fundamentally restructures the specification. The specification has
-been split into more digestible "modules" which each describe a particular
-function (e.g. typing). This was done in order make the specification easier to
-maintain and help define which modules are mandatory for certain types
-of clients. Types of clients along with the mandatory modules can be found in a
-new "Feature Profiles" section. This update also begins to aggressively
-standardise on using Swagger and JSON Schema to document HTTP endpoints and
-Events respectively. It also introduces a number of new concepts to Matrix.
-
-Additions:
- - New section: Feature Profiles.
- - New section: Receipts.
- - New section: Room history visibility.
- - New event: ``m.receipt``.
- - New event: ``m.room.canonical_alias``
- - New event: ``m.room.history_visibility``
- - New keys: ``/createRoom`` - allows room "presets" using ``preset`` and
-   ``initial_state`` keys.
- - New endpoint: ``/tokenrefresh`` - Related to refreshing access tokens.
-
-Modifications:
- - Convert most of the older HTTP APIs to Swagger documentation.
- - Convert most of the older event formats to JSON Schema.
- - Move selected client-server sections to be "Modules".
-
-Specification changes in v0.1.0 (2015-06-01)
-============================================
-- First numbered release.
-- Restructure the format of Event information. Add more information.
-- Restructure the format of the Client-Server HTTP APIs.

CONTRIBUTING.rst

@@ -0,0 +1,153 @@
+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).
+
+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.
+
+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.
+
+
+Other changes
+~~~~~~~~~~~~~
+
+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
+
+* 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.
+
+For such changes, please do just open a `pull request`_.
+
+
+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/).
+
+(Note that, unlike most of the other matrix.org projects, pull requests for
+matrix-doc should be based on the ``master`` branch.)
+
+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.
+
+Sign off
+~~~~~~~~
+
+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
+same lightweight approach that the Linux Kernel
+(https://www.kernel.org/doc/Documentation/SubmittingPatches), Docker
+(https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and many other
+projects use: the DCO (Developer Certificate of Origin:
+http://developercertificate.org/). This is a simple declaration that you wrote
+the contribution or otherwise have the right to contribute it to Matrix::
+
+    Developer Certificate of Origin
+    Version 1.1
+
+    Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+    660 York Street, Suite 102,
+    San Francisco, CA 94110 USA
+
+    Everyone is permitted to copy and distribute verbatim copies of this
+    license document, but changing it is not allowed.
+
+    Developer's Certificate of Origin 1.1
+
+    By making a contribution to this project, I certify that:
+
+    (a) The contribution was created in whole or in part by me and I
+        have the right to submit it under the open source license
+        indicated in the file; or
+
+    (b) The contribution is based upon previous work that, to the best
+        of my knowledge, is covered under an appropriate open source
+        license and I have the right under that license to submit that
+        work with modifications, whether created in whole or in part
+        by me, under the same open source license (unless I am
+        permitted to submit under a different license), as indicated
+        in the file; or
+
+    (c) The contribution was provided directly to me by some other
+        person who certified (a), (b) or (c) and I have not modified
+        it.
+
+    (d) I understand and agree that this project and the contribution
+        are public and that a record of the contribution (including all
+        personal information I submit with it, including my sign-off) is
+        maintained indefinitely and may be redistributed consistent with
+        this project or the open source license(s) involved.
+
+If you agree to this for your contribution, then all that's needed is to
+include the line in your commit or pull request comment::
+
+    Signed-off-by: Your Name <your@email.example.org>
+
+...using your real name; unfortunately pseudonyms and anonymous contributions
+can't be accepted. Git makes this trivial - just use the -s flag when you do
+``git commit``, having first set ``user.name`` and ``user.email`` git configs
+(which you should have done anyway :)

LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

README.rst

@@ -4,27 +4,36 @@ Structure
 =========
 
 - ``api`` : Contains the HTTP API specification.
-- ``drafts`` : Contains documents which will make it into the specification
-  and/or supporting documentation at some point in the future.
-- ``event-schemas`` : Contains the `JSON Schema`_ for all Matrix events
+- ``attic``: Contains historical sections of specification for reference
+  purposes.
+- ``changelogs``: Contains 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
   contained in the specification, along with example JSON files.
-- ``meta`` : Contains documents outlining the processes involved when writing
+- ``meta``: Contains documents outlining the processes involved when writing
   documents, e.g. documentation style, guidelines.
-- ``scripts`` : Contains scripts to generate formatted versions of the
+- ``scripts``: Contains 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 
+- ``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
+- ``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
+`<https://matrix.org/jira/browse/SPEC>`_.
 
-If you want to ask more about the specification, or have suggestions for
-improvements, join us on ``#matrix-dev:matrix.org`` via https://matrix.org/beta.
+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>`_.
 
 .. _JSON Schema: http://json-schema.org/

api/README

@@ -1,4 +1,3 @@
-To get this running:
-  python -m SimpleHTTPServer
+This directory contains swagger-compatible representations of our APIs. See
+scripts/README.md for details on how to make use of them.
 
-Go to http://localhost:8000/swagger.html

api/application-service/application_service.yaml

@@ -0,0 +1,213 @@
+# 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

api/check_examples.py

@@ -1,4 +1,18 @@
 #! /usr/bin/env python
+#
+# 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.
 
 import sys
 import json
@@ -49,7 +63,8 @@ def check_parameter(filepath, request, parameter):
             # Setting the 'id' tells jsonschema where the file is so that it
             # can correctly resolve relative $ref references in the schema
             schema['id'] = fileurl
-            jsonschema.validate(example, schema)
+            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
+            jsonschema.validate(example, schema, resolver=resolver)
         except Exception as e:
             raise ValueError("Error validating JSON schema for %r" % (
                 request
@@ -76,7 +91,8 @@ def check_response(filepath, request, code, response):
             # Setting the 'id' tells jsonschema where the file is so that it
             # can correctly resolve relative $ref references in the schema
             schema['id'] = fileurl
-            jsonschema.validate(example, schema)
+            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
+            jsonschema.validate(example, schema, resolver=resolver)
         except Exception as e:
             raise ValueError("Error validating JSON schema for %r %r" % (
                 request, code
@@ -103,6 +119,14 @@ def check_swagger_file(filepath):
                 check_response(filepath, request, code, response)
 
 
+def load_yaml(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 __name__ == '__main__':
     paths = sys.argv[1:]
     if not paths:

api/client-server/account-data.yaml

@@ -0,0 +1,118 @@
+# 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 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:
+  "/user/{userId}/account_data/{type}":
+    put:
+      summary: Set some account_data for the user.
+      description: |-
+        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``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to set account_data for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: type
+          required: true
+          description: |-
+            The event type of the account_data to set. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.config"
+        - in: body
+          name: content
+          required: true
+          description: |-
+            The content of the account_data
+          schema:
+            type: object
+            example: |-
+              {"custom_account_data_key": "custom_config_value"}
+      responses:
+        200:
+          description:
+            The account_data was successfully added.
+      tags:
+        - User data
+  "/user/{userId}/rooms/{roomId}/account_data/{type}":
+    put:
+      summary: Set some account_data for the user.
+      description: |-
+        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``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to set account_data for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: |-
+            The id of the room to set account_data on.
+          x-example: "!726s6s6q:example.com"
+        - in: path
+          type: string
+          name: type
+          required: true
+          description: |-
+            The event type of the account_data to set. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.room.config"
+        - in: body
+          name: content
+          required: true
+          description: |-
+            The content of the account_data
+          schema:
+            type: object
+            example: |-
+              {"custom_account_data_key": "custom_account_data_value"}
+      responses:
+        200:
+          description:
+            The account_data was successfully added.
+      tags:
+        - User data

api/client-server/admin.yaml

@@ -0,0 +1,114 @@
+# 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 Client-Server Administration 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:
+  "/admin/whois/{userId}":
+    get:
+      summary: Gets information about a particular user.
+      description: |-
+        Gets information about a particular user.
+
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user to look up.
+          required: true
+          x-example: "@peter:rabbit.rocks"
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@peter:rabbit.rocks",
+                "devices": {
+                  "teapot": {
+                    "sessions": [
+                      {
+                        "connections": [
+                          {
+                            "ip": "127.0.0.1",
+                            "last_seen": 1411996332123,
+                            "user_agent": "curl/7.31.0-DEV"
+                          },
+                          {
+                            "ip": "10.0.0.2",
+                            "last_seen": 1411996332123,
+                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The Matrix user ID of the user.
+              devices:
+                type: object
+                description: |-
+                  Each key is an identitfier for one of the user's devices.
+                additionalProperties:
+                  type: object
+                  title: DeviceInfo
+                  properties:
+                    sessions:
+                      type: array
+                      description: A user's sessions (i.e. what they did with an access token from one login).
+                      items:
+                        type: object
+                        title: SessionInfo
+                        properties:
+                          connections:
+                            type: array
+                            description: Information particular connections in the session.
+                            items:
+                              type: object
+                              title: ConnectionInfo
+                              properties:
+                                ip:
+                                  type: string
+                                  description: Most recently seen IP address of the session.
+                                last_seen:
+                                  type: number
+                                  description: Unix timestamp that the session was last active.
+                                user_agent:
+                                  type: string
+                                  description: User agent string last seen in the session.
+      tags:
+        - Server administration

api/client-server/administrative_contact.yaml

@@ -0,0 +1,147 @@
+# 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 Client-Server Account Administrative Contact 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:
+  "/account/3pid":
+    get:
+      summary: Gets a list of a user's third party identifiers.
+      description: |-
+        Gets a list of the third party identifiers that the homeserver has
+        associated with the user's account.
+
+        This is *not* the same as the list of third party identifiers bound to
+        the user's Matrix ID in Identity Servers.
+
+        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.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: |-
+              {
+                "threepids": [
+                  {
+                    "medium": "email",
+                    "address": "monkey@banana.island"
+                  }
+                ]
+              }
+          schema:
+            type: object
+            properties:
+              threepids:
+                type: array
+                items:
+                  type: object
+                  title: Third party identifier
+                  properties:
+                    medium:
+                      type: string
+                      description: The medium of the third party identifier.
+                      enum: ["email"]
+                    address:
+                      type: string
+                      description: The third party identifier address.
+      tags:
+        - User data
+    post:
+      summary: Adds contact information to the user's account.
+      description: Adds contact information to the user's account.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              three_pid_creds:
+                title: "ThreePidCredentials"
+                type: object
+                description: The third party credentials to associate with the account.
+                properties:
+                  client_secret:
+                    type: string
+                    description: The client secret used in the session with the Identity Server.
+                  id_server:
+                    type: string
+                    description: The Identity Server to use.
+                  sid:
+                    type: string
+                    description: The session identifier given by the Identity Server.
+                required: ["client_secret", "id_server", "sid"]
+              bind:
+                type: boolean
+                description: |-
+                  Whether the homeserver should also bind this third party
+                  identifier to the account's Matrix ID with the passed identity
+                  server. Default: ``false``.
+                x-example: true
+            required: ["three_pid_creds"]
+            example: |-
+              {
+                "three_pid_creds": {
+                  "id_server": "matrix.org",
+                  "sid": "abc123987",
+                  "client_secret": "d0n'tT3ll"
+                },
+                "bind": false
+              }
+      responses:
+        200:
+          description: The addition was successful.
+          examples:
+            application/json: "{}"
+            schema:
+              type: object
+        403:
+          description: The credentials could not be verified with the identity server.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_THREEPID_AUTH_FAILED",
+                "error": "The third party credentials could not be verified by the identity server."
+              }
+      tags:
+        - User data
+  "/account/3pid/email/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given email address for the purpose of adding an email address to an account
+      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. This API should be used to request
+        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.
+      responses:
+        200:
+          description: An email was sent to the given address

api/client-server/api-docs

@@ -1,50 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "apis": [
-    {
-      "path": "-login",
-      "description": "Login operations"
-    },
-    {
-      "path": "-registration",
-      "description": "Registration operations"
-    },
-    {
-      "path": "-rooms",
-      "description": "Room operations"
-    },
-    {
-      "path": "-profile",
-      "description": "Profile operations"
-    },
-    {
-      "path": "-presence",
-      "description": "Presence operations"
-    },
-    {
-      "path": "-events",
-      "description": "Event operations"
-    },
-    {
-      "path": "-directory",
-      "description": "Directory operations"
-    },
-    {
-      "path": "-content",
-      "description": "Content repository operations"
-    }
-  ],
-  "authorizations": {
-    "token": {
-      "scopes": []
-    }
-  },
-  "info": {
-    "title": "Matrix Client-Server API Reference",
-    "description": "This contains the client-server API for the reference implementation of the home server",
-    "termsOfServiceUrl": "http://matrix.org",
-    "license": "Apache 2.0",
-    "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html"
-  }
-}

api/client-server/api-docs-content

@@ -1,119 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix",
-  "resourcePath": "/media/v1/",
-  "apis": [
-    {
-      "path": "/media/v1/upload",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Upload some content to the content repository.",
-          "type": "ContentUploadResponse",
-          "nickname": "upload_content",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The file to upload.",
-              "required": true,
-              "type": "file",
-              "paramType": "body"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/media/v1/download/{serverName}/{mediaId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get the content stored at this address.",
-          "type": "file",
-          "nickname": "download_content",
-          "parameters": [
-            {
-              "name": "serverName",
-              "description": "The serverName from the mxc://<serverName>/<mediaId> URI (the authority component).",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "mediaId",
-              "description": "The mediaId from the mxc://<serverName>/<mediaId> URI (the path component).",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/media/v1/thumbnail/{serverName}/{mediaId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a thumbnail of the content stored at this address.",
-          "type": "file",
-          "nickname": "thumbnail_content",
-          "parameters": [
-            {
-              "name": "serverName",
-              "description": "The serverName from the mxc://<serverName>/<mediaId> URI (the authority component).",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "mediaId",
-              "description": "The mediaId from the mxc://<serverName>/<mediaId> URI (the path component).",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "width",
-              "description": "The desired width of the thumbnail.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            },
-            {
-              "name": "height",
-              "description": "The desired height of the thumbnail.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            },
-            {
-              "name": "method",
-              "description": "The desired resizing method.",
-              "enum": [
-                "crop",
-                "scale"
-              ],
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "ContentUploadResponse": {
-      "id": "ContentUploadResponse",
-      "properties": {
-        "content_uri": {
-          "type": "string",
-          "description": "The mxc:// URI where this content is stored. This is of the form 'mxc://{serverName}/{mediaId}'",
-          "required": true
-        }
-      }
-    }
-  }
-}

api/client-server/api-docs-directory

@@ -1,101 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/directory",
-  "produces": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/directory/room/{roomAlias}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get the room ID corresponding to this room alias.",
-          "notes": "Volatile: This API is likely to change.",
-          "type": "DirectoryResponse",
-          "nickname": "get_room_id_for_alias",
-          "parameters": [
-            {
-              "name": "roomAlias",
-              "description": "The room alias.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "PUT",
-          "summary": "Create a new mapping from room alias to room ID.",
-          "notes": "Volatile: This API is likely to change.",
-          "type": "void",
-          "nickname": "add_room_alias",
-          "parameters": [
-            {
-              "name": "roomAlias",
-              "description": "The room alias to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The room ID to set.",
-              "required": true,
-              "type": "RoomAliasRequest",
-              "paramType": "body"
-            }
-          ]
-        },
-        {
-          "method": "DELETE",
-          "summary": "Removes a mapping of room alias to room ID.",
-          "notes": "Only privileged users can perform this action.",
-          "type": "void",
-          "nickname": "remove_room_alias",
-          "parameters": [
-            {
-              "name": "roomAlias",
-              "description": "The room alias to remove.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "DirectoryResponse": {
-      "id": "DirectoryResponse",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The fully-qualified room ID.",
-          "required": true
-        },
-        "servers": {
-          "type": "array",
-          "items": {
-            "$ref": "string"
-          },
-          "description": "A list of servers that know about this room.",
-          "required": true
-        }
-      }
-    },
-    "RoomAliasRequest": {
-      "id": "RoomAliasRequest",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The room ID to map the alias to.",
-          "required": true
-        }
-      }
-    }
-  }
-}

api/client-server/api-docs-events

@@ -1,247 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/events",
-  "produces": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/events",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Listen on the event stream",
-          "notes": "This can only be done by the logged in user. This will block until an event is received, or until the timeout is reached.",
-          "type": "PaginationChunk",
-          "nickname": "get_event_stream",
-          "parameters": [
-            {
-              "name": "from",
-              "description": "The token to stream from.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "timeout",
-              "description": "The maximum time in milliseconds to wait for an event.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            }
-          ]
-        }
-      ],
-      
-      "responseMessages": [
-        {
-          "code": 400,
-          "message": "Bad pagination token."
-        }
-      ]
-    },
-    {
-      "path": "/events/{eventId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get information about a single event.",
-          "notes": "Get information about a single event.",
-          "type": "Event",
-          "nickname": "get_event",
-          "parameters": [
-            {
-              "name": "eventId",
-              "description": "The event ID to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 404,
-              "message": "Event not found."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/initialSync",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get this user's current state.",
-          "notes": "Get this user's current state.",
-          "type": "InitialSyncResponse",
-          "nickname": "initial_sync",
-          "parameters": [
-            {
-              "name": "limit",
-              "description": "The maximum number of messages to return for each room.",
-              "type": "integer",
-              "paramType": "query",
-              "required": false
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/publicRooms",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a list of publicly visible rooms.",
-          "type": "PublicRoomsPaginationChunk",
-          "nickname": "get_public_room_list"
-        }
-      ]
-    }
-  ],
-  "models": {
-    "PaginationChunk": {
-      "id": "PaginationChunk",
-      "properties": {
-        "start": {
-          "type": "string",
-          "description": "A token which correlates to the first value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "end": {
-          "type": "string",
-          "description": "A token which correlates to the last value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "chunk": {
-          "type": "array",
-          "description": "An array of events.",
-          "required": true,
-          "items": {
-            "$ref": "Event"
-          }
-        }
-      }
-    },
-    "Event": {
-      "id": "Event",
-      "properties": {
-        "event_id": {
-          "type": "string",
-          "description": "An ID which uniquely identifies this event.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The room in which this event occurred.",
-          "required": true
-        }
-      }
-    },
-    "PublicRoomInfo": {
-      "id": "PublicRoomInfo",
-      "properties": {
-        "aliases": {
-          "type": "array",
-          "description": "A list of room aliases for this room.",
-          "items": {
-            "$ref": "string"
-          }
-        },
-        "name": {
-          "type": "string",
-          "description": "The name of the room, as given by the m.room.name state event."
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The room ID for this public room.",
-          "required": true
-        },
-        "topic": {
-          "type": "string",
-          "description": "The topic of this room, as given by the m.room.topic state event."
-        }
-      }
-    },
-    "PublicRoomsPaginationChunk": {
-      "id": "PublicRoomsPaginationChunk",
-      "properties": {
-        "start": {
-          "type": "string",
-          "description": "A token which correlates to the first value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "end": {
-          "type": "string",
-          "description": "A token which correlates to the last value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "chunk": {
-          "type": "array",
-          "description": "A list of public room data.",
-          "required": true,
-          "items": {
-            "$ref": "PublicRoomInfo"
-          }
-        }
-      }
-    },
-    "InitialSyncResponse": {
-      "id": "InitialSyncResponse",
-      "properties": {
-        "end": {
-          "type": "string",
-          "description": "A streaming token which can be used with /events to continue from this snapshot of data.",
-          "required": true
-        },
-        "presence": {
-          "type": "array",
-          "description": "A list of presence events.",
-          "items": {
-            "$ref": "Event"
-          },
-          "required": false
-        },
-        "rooms": {
-          "type": "array",
-          "description": "A list of initial sync room data.",
-          "required": false,
-          "items": {
-            "$ref": "InitialSyncRoomData"
-          }
-        }
-      }
-    },
-    "InitialSyncRoomData": {
-      "id": "InitialSyncRoomData",
-      "properties": {
-        "membership": {
-          "type": "string",
-          "description": "This user's membership state in this room.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The ID of this room.",
-          "required": true
-        },
-        "messages": {
-          "type": "PaginationChunk",
-          "description": "The most recent messages for this room, governed by the limit parameter.",
-          "required": false
-        },
-        "state": {
-          "type": "array",
-          "description": "A list of state events representing the current state of the room.",
-          "required": false,
-          "items": {
-            "$ref": "Event"
-          }
-        }
-      }
-    }
-  }
-}

api/client-server/api-docs-login

@@ -1,120 +0,0 @@
-{
-  "apiVersion": "1.0.0", 
-  "apis": [
-    {
-      "operations": [
-        {
-          "method": "GET", 
-          "nickname": "get_login_info", 
-          "notes": "All login stages MUST be mentioned if there is >1 login type.", 
-          "summary": "Get the login mechanism to use when logging in.", 
-          "type": "LoginFlows"
-        }, 
-        {
-          "method": "POST", 
-          "nickname": "submit_login", 
-          "notes": "If this is part of a multi-stage login, there MUST be a 'session' key.", 
-          "parameters": [
-            {
-              "description": "A login submission", 
-              "name": "body", 
-              "paramType": "body", 
-              "required": true, 
-              "type": "LoginSubmission"
-            }
-          ], 
-          "responseMessages": [
-            {
-              "code": 400, 
-              "message": "Bad login type"
-            }, 
-            {
-              "code": 400, 
-              "message": "Missing JSON keys"
-            }
-          ], 
-          "summary": "Submit a login action.", 
-          "type": "LoginResult"
-        }
-      ], 
-      "path": "/login"
-    }
-  ], 
-  "basePath": "http://localhost:8008/_matrix/client/api/v1", 
-  "consumes": [
-    "application/json"
-  ], 
-  "models": {
-    "LoginFlows": {
-      "id": "LoginFlows",
-      "properties": {
-        "flows": {
-          "description": "A list of valid login flows.",
-          "type": "array",
-          "items": {
-            "$ref": "LoginInfo"
-          }
-        }
-      }
-    },
-    "LoginInfo": {
-      "id": "LoginInfo", 
-      "properties": {
-        "stages": {
-          "description": "Multi-stage login only: An array of all the login types required to login.", 
-          "items": {
-            "$ref": "string"
-          }, 
-          "type": "array"
-        }, 
-        "type": {
-          "description": "The login type that must be used when logging in.", 
-          "type": "string"
-        }
-      }
-    }, 
-    "LoginResult": {
-      "id": "LoginResult", 
-      "properties": {
-        "access_token": {
-          "description": "The access token for this user's login if this is the final stage of the login process.", 
-          "type": "string"
-        },
-        "user_id": {
-          "description": "The user's fully-qualified user ID.",
-          "type": "string"
-        }, 
-        "next": {
-          "description": "Multi-stage login only: The next login type to submit.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage login only: The session token to send when submitting the next login type.",
-          "type": "string"
-        }
-      }
-    }, 
-    "LoginSubmission": {
-      "id": "LoginSubmission", 
-      "properties": {
-        "type": {
-          "description": "The type of login being submitted.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage login only: The session token from an earlier login stage.",
-          "type": "string"
-        },
-        "_login_type_defined_keys_": {
-          "description": "Keys as defined by the specified login type, e.g. \"user\", \"password\""
-        }
-      }
-    }
-  }, 
-  "produces": [
-    "application/json"
-  ], 
-  "resourcePath": "/login", 
-  "swaggerVersion": "1.2"
-}
-

api/client-server/api-docs-presence

@@ -1,164 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/presence",
-  "produces": [
-    "application/json"
-  ],
-  "consumes": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/presence/{userId}/status",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Update this user's presence state.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "update_presence",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new presence state",
-              "required": true,
-              "type": "PresenceUpdate",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose presence to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get this user's presence state.",
-          "notes": "Get this user's presence state.",
-          "type": "PresenceUpdate",
-          "nickname": "get_presence",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/presence/list/{userId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Retrieve a list of presences for all of this user's friends.",
-          "notes": "",
-          "type": "array",
-          "items": {
-            "$ref": "Presence"
-          },
-          "nickname": "get_presence_list",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence list to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "POST",
-          "summary": "Add or remove users from this presence list.",
-          "notes": "Add or remove users from this presence list.",
-          "type": "void",
-          "nickname": "modify_presence_list",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence list is being modified.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The modifications to make to this presence list.",
-              "required": true,
-              "type": "PresenceListModifications",
-              "paramType": "body"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "PresenceUpdate": {
-      "id": "PresenceUpdate",
-      "properties": {
-        "presence": {
-          "type": "string",
-          "description": "Enum: The presence state.",
-          "enum": [
-            "offline",
-            "unavailable",
-            "online",
-            "free_for_chat"
-          ]
-        },
-        "status_msg": {
-          "type": "string",
-          "description": "The user-defined message associated with this presence state."
-        }
-      },
-      "subTypes": [
-        "Presence"
-      ]
-    },
-    "Presence": {
-      "id": "Presence",
-      "properties": {
-        "last_active_ago": {
-          "type": "integer",
-          "format": "int64",
-          "description": "The last time this user performed an action on their home server."
-        },
-        "user_id": {
-          "type": "string",
-          "description": "The fully qualified user ID"
-        }
-      }
-    },
-    "PresenceListModifications": {
-      "id": "PresenceListModifications",
-      "properties": {
-        "invite": {
-          "type": "array",
-          "description": "A list of user IDs to add to the list.",
-          "items": {
-            "type": "string",
-            "description": "A fully qualified user ID."
-          }
-        },
-        "drop": {
-          "type": "array",
-          "description": "A list of user IDs to remove from the list.",
-          "items": {
-            "type": "string",
-            "description": "A fully qualified user ID."
-          }
-        }
-      }
-    }
-  }
-}

api/client-server/api-docs-profile

@@ -1,122 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/profile",
-  "produces": [
-    "application/json"
-  ],
-  "consumes": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/profile/{userId}/displayname",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set a display name.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "set_display_name",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new display name for this user.",
-              "required": true,
-              "type": "DisplayName",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose display name to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get a display name.",
-          "notes": "This can be done by anyone.",
-          "type": "DisplayName",
-          "nickname": "get_display_name",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose display name to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/profile/{userId}/avatar_url",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set an avatar URL.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "set_avatar_url",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new avatar url for this user.",
-              "required": true,
-              "type": "AvatarUrl",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose avatar url to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get an avatar url.",
-          "notes": "This can be done by anyone.",
-          "type": "AvatarUrl",
-          "nickname": "get_avatar_url",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose avatar url to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "DisplayName": {
-      "id": "DisplayName",
-      "properties": {
-        "displayname": {
-          "type": "string",
-          "description": "The textual display name"
-        }
-      }
-    },
-    "AvatarUrl": {
-      "id": "AvatarUrl",
-      "properties": {
-        "avatar_url": {
-          "type": "string",
-          "description": "A url to an image representing an avatar."
-        }
-      }
-    }
-  }
-}

api/client-server/api-docs-registration

@@ -1,120 +0,0 @@
-{
-  "apiVersion": "1.0.0", 
-  "apis": [
-    {
-      "operations": [
-        {
-          "method": "GET", 
-          "nickname": "get_registration_info", 
-          "notes": "All login stages MUST be mentioned if there is >1 login type.", 
-          "summary": "Get the login mechanism to use when registering.", 
-          "type": "RegistrationFlows"
-        }, 
-        {
-          "method": "POST", 
-          "nickname": "submit_registration", 
-          "notes": "If this is part of a multi-stage registration, there MUST be a 'session' key.", 
-          "parameters": [
-            {
-              "description": "A registration submission", 
-              "name": "body", 
-              "paramType": "body", 
-              "required": true, 
-              "type": "RegistrationSubmission"
-            }
-          ], 
-          "responseMessages": [
-            {
-              "code": 400, 
-              "message": "Bad login type"
-            }, 
-            {
-              "code": 400, 
-              "message": "Missing JSON keys"
-            }
-          ], 
-          "summary": "Submit a registration action.", 
-          "type": "RegistrationResult"
-        }
-      ], 
-      "path": "/register"
-    }
-  ], 
-  "basePath": "http://localhost:8008/_matrix/client/api/v1", 
-  "consumes": [
-    "application/json"
-  ], 
-  "models": {
-    "RegistrationFlows": {
-      "id": "RegistrationFlows",
-      "properties": {
-        "flows": {
-          "description": "A list of valid registration flows.",
-          "type": "array",
-          "items": {
-            "$ref": "RegistrationInfo"
-          }
-        }
-      }
-    },
-    "RegistrationInfo": {
-      "id": "RegistrationInfo", 
-      "properties": {
-        "stages": {
-          "description": "Multi-stage registration only: An array of all the login types required to registration.", 
-          "items": {
-            "$ref": "string"
-          }, 
-          "type": "array"
-        }, 
-        "type": {
-          "description": "The first login type that must be used when logging in.", 
-          "type": "string"
-        }
-      }
-    }, 
-    "RegistrationResult": {
-      "id": "RegistrationResult", 
-      "properties": {
-        "access_token": {
-          "description": "The access token for this user's registration if this is the final stage of the registration process.", 
-          "type": "string"
-        },
-        "user_id": {
-          "description": "The user's fully-qualified user ID.",
-          "type": "string"
-        }, 
-        "next": {
-          "description": "Multi-stage registration only: The next registration type to submit.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage registration only: The session token to send when submitting the next registration type.",
-          "type": "string"
-        }
-      }
-    }, 
-    "RegistrationSubmission": {
-      "id": "RegistrationSubmission", 
-      "properties": {
-        "type": {
-          "description": "The type of registration being submitted.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage registration only: The session token from an earlier registration stage.",
-          "type": "string"
-        },
-        "_registration_type_defined_keys_": {
-          "description": "Keys as defined by the specified registration type, e.g. \"user\", \"password\""
-        }
-      }
-    }
-  }, 
-  "produces": [
-    "application/json"
-  ], 
-  "resourcePath": "/register", 
-  "swaggerVersion": "1.2"
-}
-

api/client-server/banning.yaml

@@ -0,0 +1,139 @@
+# 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 Client-Server Room Banning 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}/ban":
+    post:
+      summary: Ban a user in the room.
+      description: |-
+        Ban a user in the room. If the user is currently in the room, also kick them.
+
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be banned.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being banned.
+              reason:
+                type: string
+                description: The reason the user has been banned.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked and banned from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The banner is not currently in the room.
+            - The banner's power level is insufficient to ban users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to ban from this room."
+              }
+      tags:
+        - Room membership
+  "/rooms/{roomId}/unban":
+    post:
+      summary: Unban a user from the room.
+      description: |-
+        Unban a user from the room. This allows them to be invited to the room,
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be unbanned.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being unbanned.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been unbanned from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The unbanner's power level is insufficient to unban users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to unban from this room."
+              }
+      tags:
+        - Room membership

api/client-server/cas_login_redirect.yaml

@@ -0,0 +1,53 @@
+# 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 Client-Server CAS Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+paths:
+  "/login/cas/redirect":
+    get:
+      summary: Redirect the user's browser to the CAS interface.
+      description: |-
+        A web-based Matrix client should instruct the user's browser to
+        navigate to this endpoint in order to log in via CAS.
+
+        The server MUST respond with an HTTP redirect to the CAS interface. The
+        URI MUST include a ``service`` parameter giving the path of the
+        |/login/cas/ticket|_ endpoint (including the ``redirectUrl`` query
+        parameter).
+
+        For example, if the endpoint is called with
+        ``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``.
+
+      parameters:
+        - in: query
+          type: string
+          name: redirectUrl
+          description: |-
+            URI to which the user will be redirected after the homeserver has
+            authenticated the user with CAS.
+          required: true
+      responses:
+        302:
+          description: A redirect to the CAS interface.
+          headers:
+            Location:
+              type: "string"

api/client-server/cas_login_ticket.yaml

@@ -0,0 +1,65 @@
+# 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 Client-Server CAS Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+paths:
+  "/login/cas/ticket":
+    get:
+      summary: Receive and validate a CAS login ticket.
+      description: |-
+        Once the CAS server has authenticated the user, it will redirect the
+        browser to this endpoint (assuming |/login/cas/redirect|_ gave it the
+        correct ``service`` parameter).
+
+        The server MUST call ``/proxyValidate`` on the CAS server, to validate
+        the ticket supplied by the browser.
+
+        If validation is successful, the server must generate a Matrix login
+        token. It must then respond with an HTTP redirect to the URI given in
+        the ``redirectUrl`` parameter, adding a ``loginToken`` query parameter
+        giving the generated token.
+
+        If validation is unsuccessful, the server should respond with a ``401
+        Unauthorized`` error, the body of which will be displayed to the user.
+      parameters:
+        - in: query
+          type: string
+          name: redirectUrl
+          description: |-
+            The ``redirectUrl`` originally provided by the client to
+            |/login/cas/redirect|_.
+          required: true
+        - in: query
+          type: string
+          name: ticket
+          description: |-
+            CAS authentication ticket.
+          required: true
+      responses:
+        302:
+          description: A redirect to the Matrix client.
+          headers:
+            Location:
+              type: "string"
+              x-example: |-
+                 https://client.example.com/?q=p&loginToken=secrettoken
+        401:
+          description: The server was unable to validate the CAS ticket.

api/client-server/content-repo.yaml

@@ -1,11 +1,24 @@
+# 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 Client-Server v1 Content Repository API"
+  title: "Matrix Client-Server Content Repository API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/media/v1
+basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
 produces:
   - application/json
   - "*/*"
@@ -20,6 +33,11 @@ paths:
           type: string
           description: The content type of the file being uploaded
           x-example: "Content-Type: audio/mpeg"
+        - in: query
+          type: string
+          x-example: "War and Peace.pdf"
+          name: filename
+          description: The name of the file being uploaded
         - in: body
           name: "<content>"
           description: The content to be uploaded.
@@ -43,6 +61,8 @@ paths:
               {
                 "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
               }
+      tags:
+        - Media
   "/download/{serverName}/{mediaId}":
     get:
       summary: "Download content from the content repository."
@@ -74,6 +94,48 @@ paths:
               type: "string"
           schema:
             type: file
+      tags:
+        - Media
+  "/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      summary: "Download content from the content repository as a given filename."
+      produces: ["*/*"]
+      parameters:
+        - in: path
+          type: string
+          name: serverName
+          x-example: matrix.org
+          required: true
+          description: |
+            The server name from the ``mxc://`` URI (the authoritory component)
+        - in: path
+          type: string
+          name: mediaId
+          x-example: ascERGshawAWawugaAcauga
+          required: true
+          description: |
+            The media ID from the ``mxc://`` URI (the path component)
+        - in: path
+          type: string
+          name: fileName
+          x-example: filename.jpg
+          required: true
+          description: |
+            The filename to give in the Content-Disposition
+      responses:
+        200:
+          description: "The content that was previously uploaded."
+          headers:
+            Content-Type:
+              description: "The content type of the file that was previously uploaded."
+              type: "string"
+            Content-Disposition:
+              description: "The name of file given in the request"
+              type: "string"
+          schema:
+            type: file
+      tags:
+        - Media
   "/thumbnail/{serverName}/{mediaId}":
     get:
       summary: "Download a thumbnail of the content from the content repository."
@@ -123,5 +185,5 @@ paths:
               enum: ["image/jpeg", "image/png"]
           schema:
             type: file
-            
-
+      tags:
+        - Media

api/client-server/create_room.yaml

@@ -0,0 +1,213 @@
+# 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 Client-Server Room Creation 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:
+  "/createRoom":
+    post:
+      summary: Create a new room
+      description: |-
+        Create a new room with various configuration options.
+
+        The server MUST apply the normal state resolution rules when creating
+        the new room, including checking power levels for each event. It MUST
+        apply the events implied by the request in the following order:
+
+        1. Events set by ``presets``.
+
+        2. Events listed in ``initial_state``, in the order that they are
+           listed.
+
+        3. Events implied by ``name`` and ``topic``.
+
+        4. Invite events implied by ``invite`` and ``invite_3pid``.
+
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          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
+                }
+              }
+            properties:
+              visibility:
+                type: string
+                enum: ["public", "private"]
+                description: |-
+                  A ``public`` visibility indicates that the room will be shown
+                  in the published room list. A ``private`` visibility will hide
+                  the room from the published room list. Rooms default to
+                  ``private`` visibility if this key is not included. NB: This
+                  should not be confused with ``join_rules`` which also uses the
+                  word ``public``.
+              room_alias_name:
+                type: string
+                description: |-
+                  The desired room alias **local part**. If this is included, a
+                  room alias will be created and mapped to the newly created
+                  room. The alias will belong on the *same* homeserver which
+                  created the room. For example, if this was set to "foo" and
+                  sent to the homeserver "example.com" the complete room alias
+                  would be ``#foo:example.com``.
+              name:
+                type: string
+                description: |-
+                  If this is included, an ``m.room.name`` event will be sent
+                  into the room to indicate the name of the room. See Room
+                  Events for more information on ``m.room.name``.
+              topic:
+                type: string
+                description: |-
+                  If this is included, an ``m.room.topic`` event will be sent
+                  into the room to indicate the topic for the room. See Room
+                  Events for more information on ``m.room.topic``.
+              invite:
+                type: array
+                description: |-
+                  A list of user IDs to invite to the room. This will tell the
+                  server to invite everyone in the list to the newly created room.
+                items:
+                  type: string
+              invite_3pid:
+                type: array
+                description: |-
+                  A list of objects representing third party IDs to invite into
+                  the room.
+                items:
+                  type: object
+                  title: Invite3pid
+                  properties:
+                    id_server:
+                      type: string
+                      description: The hostname+port of the identity server which should be used for third party identifier lookups.
+                    medium:
+                      type: string
+                      # TODO: Link to identity service spec when it eixsts
+                      description: The kind of address being passed in the address field, for example ``email``.
+                    address:
+                      type: string
+                      description: The invitee's third party identifier.
+                  required: ["id_server", "medium", "address"]
+              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.
+              initial_state:
+                type: array
+                description: |-
+                  A list of state events to set in the new room. This allows
+                  the user to override the default state events set in the new
+                  room. The expected format of the state events are an object
+                  with type, state_key and content keys set.
+
+                  Takes precedence over events set by ``presets``, but gets
+                  overriden by ``name`` and ``topic`` keys.
+                items:
+                  type: object
+                  title: StateEvent
+                  properties:
+                    type:
+                      type: string
+                    state_key:
+                      type: string
+                    content:
+                      type: string
+              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:
+
+                  ``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``.
+              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.
+      responses:
+        200:
+          description: Information about the newly created room.
+          schema:
+            type: object
+            description: Information about the newly created room.
+            properties:
+              room_id:
+                type: string
+                description: |-
+                  The created room's ID.
+          examples:
+            application/json: |-
+              {
+                "room_id": "!sefiuhWgwghwWgh:example.com"
+              }
+        400:
+          description: |-
+
+            The request is invalid. A meaningful ``errcode`` and description
+            error text will be returned. Example reasons for rejection include:
+
+            - The request body is malformed (``errcode`` set to ``M_BAD_JSON``
+              or ``M_NOT_JSON``).
+
+            - The room alias specified is already taken (``errcode`` set to
+              ``M_ROOM_IN_USE``).
+
+            - The initial state implied by the parameters to the request is
+              invalid: for example, the user's ``power_level`` is set below
+              that necessary to set the room name (``errcode`` set to
+              ``M_INVALID_ROOM_STATE``).
+
+      tags:
+        - Room creation

api/client-server/definitions/auth_data.yaml

@@ -0,0 +1,33 @@
+# 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.
+title: Authentication Data
+description: |-
+  Used by clients to submit authentication information to the interactive-authentication API
+type: object
+properties:
+  type:
+    description: The login type that the client is attempting to complete.
+    type: string
+  session:
+    description: The value of the session key given by the homeserver.
+    type: string
+additionalProperties:
+  description: Keys dependent on the login type
+  type: object
+required:
+  - type
+example:
+  type: "example.type.foo"
+  session: "xxxxx"
+  example_credential: "verypoorsharedsecret"

api/client-server/definitions/auth_response.yaml

@@ -0,0 +1,62 @@
+# 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.
+title: Authentication response
+description: |-
+  Used by servers to indicate that additional authentication information is required,
+type: object
+properties:
+  flows:
+    description: A list of the login flows supported by the server for this API.
+    title: Flow information
+    type: array
+    items:
+      type: object
+      properties:
+        stages:
+          description: |-
+            The login type of each of the stages required to complete this
+            authentication flow
+          type: array
+          items:
+            type: string
+            example: "example.type.foo"
+      required:
+        - stages
+  params:
+    type: object
+    description: |-
+      Contains any information that the client will need to know in order to
+      use a given type of authentication. For each login type presented,
+      that type may be present as a key in this dictionary. For example, the
+      public part of an OAuth client ID could be given here.
+    additionalProperties:
+      type: object
+    example:
+      "example.type.baz": { "example_key": "foobar" }
+  session:
+    type: string
+    description: |-
+      This is a session identifier that the client must pass back to the home
+      server, if one is provided, in subsequent attempts to authenticate in the
+      same API call.
+    example: "xxxxxxyz"
+  completed:
+    type: array
+    description: |-
+      A list of the stages the client has completed successfully
+    items:
+      type: string
+      example: "example.type.foo"
+required:
+  - flows

api/client-server/definitions/client_device.yaml

@@ -0,0 +1,44 @@
+# 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
+description: A client device
+title: Device
+properties:
+  device_id:
+    type: string
+    description: Identifier of this device.
+    example: QBUAZIFURK
+  display_name:
+    type: string
+    description: |-
+      Display name set by the user for this device. Absent if no name has been
+      set.
+    example: android
+  last_seen_ip:
+    type: string
+    description: |-
+      The IP address where this device was last seen. (May be a few minutes out
+      of date, for efficiency reasons).
+    example: 1.2.3.4
+  last_seen_ts:
+    type: integer
+    format: int64
+    description: |-
+      The timestamp (in milliseconds since the unix epoch) when this devices
+      was last seen. (May be a few minutes out of date, for efficiency
+      reasons).
+    example: 1474491775024
+required:
+  - device_id

api/client-server/definitions/device_keys.yaml

@@ -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

api/client-server/definitions/error.yaml

@@ -0,0 +1,23 @@
+# 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
+description: A Matrix-level Error
+properties:
+  errcode:
+    type: string
+    description: An error code.
+  error:
+    type: string
+    description: A human-readable error message.
+required: ["errcode"]

api/client-server/definitions/event-schemas

@@ -0,0 +1 @@
+../../../event-schemas

api/client-server/definitions/event.yaml

@@ -0,0 +1,62 @@
+# 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.
+properties:
+  content:
+    description: The content of this event. The fields in this object will vary depending
+      on the type of event.
+    title: EventContent
+    type: object
+  origin_server_ts:
+    description: Timestamp in milliseconds on originating homeserver when this event
+      was sent.
+    format: int64
+    type: integer
+  sender:
+    description: The MXID of the user who sent this event.
+    type: string
+  state_key:
+    description: Optional. This key will only be present for state events. A unique
+      key which defines the overwriting semantics for this piece of room state.
+    type: string
+  type:
+    description: The type of event.
+    type: string
+  unsigned:
+    description: Information about this event which was not sent by the originating
+      homeserver
+    properties:
+      age:
+        description: Time in milliseconds since the event was sent.
+        format: int64
+        type: integer
+      prev_content:
+        description: Optional. The previous ``content`` for this state. This will
+          be present only for state events appearing in the ``timeline``. If this
+          is not a state event, or there is no previous content, this key will be
+          missing.
+        title: EventContent
+        type: object
+      transaction_id:
+        description: Optional. The transaction ID set when this message was sent.
+          This key will only be present for message events sent by the device calling
+          this API.
+        type: string
+      redacted_because:
+        description: Optional. The event that redacted this event, if any.
+        title: Event
+        type: object
+    title: Unsigned
+    type: object
+title: Event
+type: object

api/client-server/definitions/event_batch.yaml

@@ -0,0 +1,22 @@
+# 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.
+properties:
+  events:
+    description: List of events
+    items:
+      allOf:
+      - $ref: event.yaml
+      type: object
+    type: array
+type: object

api/client-server/definitions/event_filter.yaml

@@ -0,0 +1,47 @@
+# 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.
+title: Filter
+properties:
+  limit:
+    description: The maximum number of events to return.
+    type: integer
+  not_senders:
+    description: A list of sender IDs to exclude. If this list is absent then no senders
+      are excluded. A matching sender will be excluded even if it is listed in the
+      ``'senders'`` filter.
+    items:
+      type: string
+    type: array
+  not_types:
+    description: A list of event types to exclude. If this list is absent then no
+      event types are excluded. A matching type will be excluded even if it is listed
+      in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence
+      of characters.
+    items:
+      type: string
+    type: array
+  senders:
+    description: A list of senders IDs to include. If this list is absent then all
+      senders are included.
+    items:
+      type: string
+    type: array
+  types:
+    description: A list of event types to include. If this list is absent then all
+      event types are included. A ``'*'`` can be used as a wildcard to match any sequence
+      of characters.
+    items:
+      type: string
+    type: array
+type: object

api/client-server/definitions/push_condition.yaml

@@ -0,0 +1,45 @@
+# 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.
+
+title: PushCondition
+type: object
+properties:
+  kind:
+    enum:
+    - event_match
+    - contains_display_name
+    - room_member_count
+    type: string
+  key:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The dot-separated field of the
+      event to match.
+    x-example: content.body
+  pattern:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The glob-style pattern to
+      match against. Patterns with no special glob characters should be
+      treated as having asterisks prepended and appended when testing the
+      condition.
+  is:
+    type: string
+    description: |-
+      Required for ``room_member_count`` conditions. A decimal integer
+      optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches
+      rooms where the member count is strictly less than the given number and
+      so forth. If no prefix is present, this parameter defaults to ==.
+required:
+  - kind

api/client-server/definitions/push_rule.yaml

@@ -0,0 +1,56 @@
+# 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.
+
+title: PushRule
+type: object
+properties:
+  actions:
+    items:
+      type:
+      - object
+      - string
+    type: array
+    description: |-
+      The actions to perform when this rule is matched.
+  default:
+    type: boolean
+    description: |-
+      Whether this is a default rule, or has been set explicitly.
+  enabled:
+    type: boolean
+    description: |-
+      Whether the push rule is enabled or not.
+  rule_id:
+    type: string
+    description: |-
+      The ID of this rule.
+  conditions:
+    type: array
+    items:
+      allOf:
+      - $ref: push_condition.yaml
+    description: |-
+      The conditions that must hold true for an event in order for a rule to be
+      applied to an event. A rule with no conditions always matches. Only
+      applicable to ``underride`` and ``override`` rules.
+  pattern:
+    type: string
+    description: |-
+      The glob-style pattern to match against.  Only applicable to ``content``
+      rules.
+required:
+  - actions
+  - default
+  - enabled
+  - rule_id

api/client-server/definitions/push_ruleset.yaml

@@ -0,0 +1,50 @@
+# 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.
+properties:
+  content:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  override:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  room:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  sender:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+  underride:
+    items:
+      allOf:
+      - $ref: push_rule.yaml
+      title: PushRule
+      type: object
+    type: array
+type: object

api/client-server/definitions/room_event_filter.yaml

@@ -0,0 +1,35 @@
+# 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.
+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

api/client-server/definitions/security.yaml

@@ -0,0 +1,18 @@
+# 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.
+accessToken:
+  type: apiKey
+  description: The access_token returned by a call to ``/login`` or ``/register``
+  name: access_token
+  in: query

api/client-server/definitions/sync_filter.yaml

@@ -0,0 +1,80 @@
+# 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.
+properties:
+  event_fields:
+    description: List of event fields to include. If this list is absent then all
+      fields are included. The entries may include '.' charaters to indicate sub-fields.
+      So ['content.body'] will include the 'body' field of the 'content' object. A
+      literal '.' character in a field name may be escaped using a '\\'. A server may
+      include more fields than were requested.
+    items:
+      type: string
+    type: array
+  event_format:
+    description: The format to use for events. 'client' will return the events in
+      a format suitable for clients. 'federation' will return the raw event as receieved
+      over federation. The default is 'client'.
+    enum:
+    - client
+    - federation
+    type: string
+  presence:
+    allOf:
+    - $ref: event_filter.yaml
+    description: The presence updates to include.
+  account_data:
+    allOf:
+    - $ref: event_filter.yaml
+    description: The user account data that isn't associated with rooms to include.
+  room:
+    title: RoomFilter
+    description: Filters to be applied to room data.
+    properties:
+      not_rooms:
+        description: A list of room IDs to exclude. If this list is absent then no rooms
+          are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
+          filter. This filter is applied before the filters in ``ephemeral``, 
+          ``state``, ``timeline`` or ``account_data``
+        items:
+          type: string
+        type: array
+      rooms:
+        description: A list of room IDs to include. If this list is absent then all rooms
+          are included. This filter is applied before the filters in ``ephemeral``,
+          ``state``, ``timeline`` or ``account_data``
+        items:
+          type: string
+        type: array
+      ephemeral:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The events that aren't recorded in the room history, e.g. typing
+          and receipts, to include for rooms.
+      include_leave:
+        description: Include rooms that the user has left in the sync, default false
+        type: boolean
+      state:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The state events to include for rooms.
+      timeline:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The message and state update events to include for rooms.
+      account_data:
+        allOf:
+        - $ref: room_event_filter.yaml
+        description: The per user account data to include for rooms.
+    type: object
+type: object

api/client-server/definitions/timeline_batch.yaml

@@ -0,0 +1,25 @@
+# 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.
+allOf:
+- $ref: event_batch.yaml
+properties:
+  limited:
+    description: True if the number of events returned was limited by the ``limit``
+      on the filter
+    type: boolean
+  prev_batch:
+    description: A token that can be supplied to to the ``from`` parameter of the
+      rooms/{roomId}/messages endpoint
+    type: string
+type: object

api/client-server/device_management.yaml

@@ -0,0 +1,177 @@
+# 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 Client-Server device management 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:
+  "/devices":
+    get:
+      summary: List registered devices for the current user
+      description: |-
+        Gets information about all devices for the current user.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            properties:
+              devices:
+                type: array
+                description: A list of all registered devices for this user.
+                items:
+                  type: object
+                  allOf:
+                    - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: |-
+              {
+                "devices": [
+                  {
+                    "device_id": "QBUAZIFURK",
+                    "display_name": "android",
+                    "last_seen_ip": "1.2.3.4",
+                    "last_seen_ts": 1474491775024
+                  }
+                ]
+              }
+      tags:
+        - Device management
+  "/devices/{deviceId}":
+    get:
+      summary: Get a single device
+      description: |-
+        Gets information on a single device, by device id.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to retrieve.
+          required: true
+          x-example: "QBUAZIFURK"
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            allOf:
+               - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: |-
+              {
+                "device_id": "QBUAZIFURK",
+                "display_name": "android",
+                "last_seen_ip": "1.2.3.4",
+                "last_seen_ts": 1474491775024
+              }
+        404:
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    put:
+      summary: Update a device
+      description: |-
+        Updates the metadata on the given device.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to update.
+          required: true
+          x-example: "QBUAZIFURK"
+        - in: body
+          name: body
+          required: true
+          description: New information for the device.
+          schema:
+            type: object
+            properties:
+              display_name:
+                type: string
+                description: |-
+                    The new display name for this device. If not given, the
+                    display name is unchanged.
+                example: My other phone
+      responses:
+        200:
+          description: The device was successfully updated.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        404:
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    delete:
+      summary: Delete a device
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Deletes the given device, and invalidates any access token assoicated with it.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to delete.
+          required: true
+          x-example: "QBUAZIFURK"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+      responses:
+        200:
+          description: |-
+            The device was successfully removed, or had been removed
+            previously.
+          schema:
+            type: object
+          examples:
+            application/json: |-
+              {}
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+      tags:
+        - Device management

api/client-server/directory.yaml

@@ -0,0 +1,149 @@
+# 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 Client-Server Directory API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%/directory
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/room/{roomAlias}":
+    put:
+      summary: Create a new mapping from room alias to room ID.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomAlias
+          description: The room alias to set.
+          required: true
+          x-example: "#monkeys:matrix.org"
+        - in: body
+          name: roomInfo
+          description: Information about this room alias.
+          required: true
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID to set.
+            example: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com"
+              }
+      responses:
+        200:
+          description: The mapping was created.
+          examples:
+            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."
+              }
+      tags:
+        - Room directory
+    get:
+      summary: Get the room ID corresponding to this room alias.
+      description: |-
+        Requests that the server resolve a room alias to a room ID.
+
+        The server will use the federation API to resolve the alias if the
+        domain part of the alias does not correspond to the server's own
+        domain.
+
+      parameters:
+        - in: path
+          type: string
+          name: roomAlias
+          description: The room alias.
+          required: true
+          x-example: "#monkeys:matrix.org"
+      responses:
+        200:
+          description: The room ID and other information for this alias.
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID for this room alias.
+              servers:
+                type: array
+                description: A list of servers that are aware of this room alias.
+                items:
+                  type: string
+                  description: A server which is aware of this room alias.
+          examples:
+            application/json: |-
+              {
+                "room_id": "!abnjk1jdasj98:capuchins.com",
+                "servers": [
+                  "capuchins.com",
+                  "matrix.org",
+                  "another.com"
+                ]
+              }
+        404:
+          description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_NOT_FOUND",
+                "error": "Room alias #monkeys:matrix.org not found."
+              }
+      tags:
+        - Room directory
+    delete:
+      summary: Remove a mapping of room alias to room ID.
+      description: |-
+        Remove a mapping of room alias to room ID.
+
+        Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomAlias
+          description: The room alias to remove.
+          required: true
+          x-example: "#monkeys:matrix.org"
+      responses:
+        200:
+          description: The mapping was deleted.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+      tags:
+        - Room directory

api/client-server/event_context.yaml

@@ -0,0 +1,165 @@
+# 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 Client-Server Event Context 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}/context/{eventId}":
+    get:
+      summary: Get events and state around the specified event.
+      description: |-
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get events from.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The event to get context around.
+          required: true
+          x-example: "$f3h4d129462ha:example.com"
+        - in: query
+          type: integer
+          name: limit
+          description: |-
+            The maximum number of events to return. Default: 10.
+          x-example: 3
+      responses:
+        200:
+          description: The events and state surrounding the requested event.
+          schema:
+            type: object
+            description: The events and state surrounding the requested event.
+            properties:
+              start:
+                type: string
+                description: |-
+                  A token that can be used to paginate backwards with.
+              end:
+                type: string
+                description: |-
+                  A token that can be used to paginate forwards with.
+              events_before:
+                type: array
+                description: |-
+                  A list of room events that happened just before the
+                  requested event, in reverse-chronological order.
+                items:
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+              event:
+                description: |-
+                  Details of the requested event.
+                allOf:
+                  - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+              events_after:
+                type: array
+                description: |-
+                  A list of room events that happened just after the
+                  requested event, in chronological order.
+                items:
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+              state:
+                type: array
+                description: |-
+                  The state of the room at the last event returned.
+                items:
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
+          examples:
+            application/json: |-
+                {
+                  "end": "t29-57_2_0_2",
+                  "events_after": [
+                    {
+                      "age": 91911336,
+                      "content": {
+                        "body": "7",
+                        "msgtype": "m.text"
+                      },
+                      "event_id": "$14460306086CiUaL:localhost:8480",
+                      "origin_server_ts": 1446030608551,
+                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
+                      "type": "m.room.message",
+                      "sender": "@test:localhost:8480"
+                    }
+                  ],
+                  "events_before": [
+                    {
+                      "age": 91911903,
+                      "content": {
+                        "body": "5",
+                        "msgtype": "m.text"
+                      },
+                      "event_id": "$14460306074UYTlh:localhost:8480",
+                      "origin_server_ts": 1446030607984,
+                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
+                      "type": "m.room.message",
+                      "sender": "@test:localhost:8480"
+                    }
+                  ],
+                  "start": "t27-54_2_0_2",
+                  "state": [
+                    {
+                      "age": 3123715284,
+                      "content": {
+                        "creator": "@test:localhost:8480"
+                      },
+                      "event_id": "$14429988040dgQAE:localhost:8480",
+                      "origin_server_ts": 1442998804603,
+                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
+                      "state_key": "",
+                      "type": "m.room.create",
+                      "sender": "@test:localhost:8480"
+                    },
+                    {
+                      "age": 2067105053,
+                      "content": {
+                        "avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
+                        "displayname": "Bob2",
+                        "membership": "join"
+                      },
+                      "event_id": "$14440554144URDbf:localhost:8480",
+                      "origin_server_ts": 1444055414834,
+                      "replaces_state": "$14440552472PgiGk:localhost:8480",
+                      "room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
+                      "state_key": "@test:localhost:8480",
+                      "type": "m.room.member",
+                      "sender": "@test:localhost:8480"
+                    }
+                  ]
+                }
+      tags:
+        - Room participation

api/client-server/filter.yaml

@@ -1,29 +1,38 @@
+# 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 Client-Server v2 filter API"
+  title: "Matrix Client-Server filter API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/user/{userId}/filter":
     post:
       summary: Upload a new filter.
       description: |-
         Uploads a new filter definition to the homeserver.
-        Returns a filter ID that may be used in /sync requests to
-        retrict which events are returned to the client.
+        Returns a filter ID that may be used in future requests to
+        restrict which events are returned to the client.
       security:
         - accessToken: []
       parameters:
@@ -42,7 +51,7 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
             example: |-
               {
                 "room": {
@@ -56,7 +65,7 @@ paths:
                     "not_rooms": ["!726s6s6q:example.com"],
                     "not_senders": ["@spam:example.com"]
                   },
-                  "emphemeral": {
+                  "ephemeral": {
                     "types": ["m.receipt", "m.typing"],
                     "not_rooms": ["!726s6s6q:example.com"],
                     "not_senders": ["@spam:example.com"]
@@ -84,9 +93,13 @@ paths:
                 type: string
                 description: |-
                   The ID of the filter that was created.
+      tags:
+        - Room participation
   "/user/{userId}/filter/{filterId}":
     get:
       summary: Download a filter
+      security:
+        - accessToken: []
       parameters:
         - in: path
           name: userId
@@ -120,7 +133,7 @@ paths:
                     "not_rooms": ["!726s6s6q:example.com"],
                     "not_senders": ["@spam:example.com"]
                   },
-                  "emphemeral": {
+                  "ephemeral": {
                     "types": ["m.receipt", "m.typing"],
                     "not_rooms": ["!726s6s6q:example.com"],
                     "not_senders": ["@spam:example.com"]
@@ -136,4 +149,6 @@ paths:
           schema:
             type: object
             allOf:
-              - $ref: "definitions/sync_filter.json"
+              - $ref: "definitions/sync_filter.yaml"
+      tags:
+        - Room participation

api/client-server/inviting.yaml

@@ -0,0 +1,101 @@
+# 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 Client-Server Room Joining 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:
+  # With an extra " " to disambiguate from the 3pid invite endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
+  "/rooms/{roomId}/invite ":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        .. _invite-by-user-id-endpoint:
+
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API requires that the inviter knows the Matrix
+        identifier of the invitee. The other is documented in the*
+        `third party invites section`_.
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the user was invited to the room, the homeserver will append a
+        ``m.room.member`` event to the room.
+
+        .. _third party invites section: `invite-by-third-party-id-endpoint`_
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the invitee.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been invited to join the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - 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"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/joining.yaml

@@ -0,0 +1,214 @@
+# 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 Client-Server Room Inviting 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}/join":
+    post:
+      summary: Start the requesting user participating in a particular room.
+      description: |-
+        *Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
+
+        This API starts a user participating in a particular room, if that user
+        is allowed to participate in that room. After this call, the client is
+        allowed to see all current state events in the room, and all subsequent
+        events associated with the room until the user leaves the room.
+
+        After a user has joined a room, the room will appear as an entry in the
+        response of the |/initialSync|_ and |/sync|_ APIs.
+
+        If a ``third_party_signed`` was supplied, the homeserver must verify
+        that it matches a pending ``m.room.third_party_invite`` event in the
+        room, and perform key validity checking if required by the event.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) to join.
+          required: true
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: third_party_signed
+          schema:
+            type: object
+            example: |-
+              {
+                "third_party_signed": {
+                  "sender": "@cat:the.hat",
+                  "mxid": "@green:eggs.ham",
+                  "token": "random8nonce",
+                  "signatures": {
+                    "horton.hears": {
+                      "ed25519:0": "some9signature"
+                    }
+                  }
+                }
+              }
+            properties:
+              third_party_signed:
+                type: object
+                title: ThirdPartySigned
+                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
+                properties:
+                  sender:
+                    type: string
+                    description: The Matrix ID of the user who issued the invite.
+                  mxid:
+                    type: string
+                    description: The Matrix ID of the invitee.
+                  token:
+                    type: string
+                    description: The state key of the m.third_party_invite event.
+                  signatures:
+                    type: object
+                    description: A signatures object containing a signature of the entire signed object.
+                    title: Signatures
+                required: ["sender", "mxid", "token", "signatures"]
+      responses:
+        200:
+          description: |-
+            The room has been joined.
+
+            The joined room ID must be returned in the ``room_id`` field.
+          examples:
+            application/json: |-
+              {"room_id": "!d41d8cd:matrix.org"}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+
+            - 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."}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership
+  "/join/{roomIdOrAlias}":
+    post:
+      summary: Start the requesting user participating in a particular room.
+      description: |-
+        *Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``.
+
+        This API starts a user participating in a particular room, if that user
+        is allowed to participate in that room. After this call, the client is
+        allowed to see all current state events in the room, and all subsequent
+        events associated with the room until the user leaves the room.
+
+        After a user has joined a room, the room will appear as an entry in the
+        response of the |/initialSync|_ and |/sync|_ APIs.
+
+        If a ``third_party_signed`` was supplied, the homeserver must verify
+        that it matches a pending ``m.room.third_party_invite`` event in the
+        room, and perform key validity checking if required by the event.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomIdOrAlias
+          description: The room identifier or alias to join.
+          required: true
+          x-example: "#monkeys:matrix.org"
+        - in: body
+          name: third_party_signed
+          schema:
+            type: object
+            example: |-
+              {
+                "third_party_signed": {
+                  "signed": {
+                    "sender": "@cat:the.hat",
+                    "mxid": "@green:eggs.ham",
+                    "token": "random8nonce",
+                    "signatures": {
+                      "horton.hears": {
+                        "ed25519:0": "some9signature"
+                      }
+                    }
+                  }
+                }
+              }
+            properties:
+              third_party_signed:
+                type: object
+                title: ThirdPartySigned
+                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
+                properties:
+                  signed:
+                    type: object
+                    title: Signed
+                    properties:
+                      sender:
+                        type: string
+                        description: The Matrix ID of the user who issued the invite.
+                      mxid:
+                        type: string
+                        description: The Matrix ID of the invitee.
+                      token:
+                        type: string
+                        description: The state key of the m.third_party_invite event.
+                      signatures:
+                        type: object
+                        description: A signatures object containing a signature of the entire signed object.
+                        title: Signatures
+                    required: ["sender", "mxid", "token", "signatures"]
+                required: ["signed"]
+      responses:
+        200:
+          description: |-
+            The room has been joined.
+
+            The joined room ID must be returned in the ``room_id`` field.
+          examples:
+            application/json: |-
+              {"room_id": "!d41d8cd:matrix.org"}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+
+            - 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."}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/keys.yaml

@@ -0,0 +1,336 @@
+# 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 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.
+      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.
+      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": []
+            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.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.
+      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": "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 ``<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``.
+      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:
+              changes:
+                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"]
+      tags:
+        - End-to-end encryption

api/client-server/kicking.yaml

@@ -0,0 +1,86 @@
+# 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 Client-Server Room Kicking 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}/kick":
+    post:
+      summary: Kick a user from the room.
+      description: |-
+        Kick a user from the room.
+
+        The caller must have the required power level in order to perform this operation.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) from which the user should be kicked.
+          required: true
+          x-example: "!e42d8c:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the user being kicked.
+              reason:
+                type: string
+                description: The reason the user has been kicked.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked from the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The kicker is not currently in the room.
+            - The kickee is not currently in the room.
+            - The kicker's power level is insufficient to kick users from the room.
+          examples:
+            application/json: |-
+              {
+                "errcode": "M_FORBIDDEN",
+                "error": "You do not have a high enough power level to kick from this room."
+              }
+      tags:
+        - Room membership

api/client-server/leaving.yaml

@@ -0,0 +1,105 @@
+# 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 Client-Server Room Leaving 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}/leave":
+    post:
+      summary: Stop the requesting user participating in a particular room.
+      description: |-
+        This API stops a user participating in a particular room.
+
+        If the user was already in the room, they will no longer be able to see
+        new events in the room. If the room requires an invite to join, they
+        will need to be re-invited before they can re-join.
+
+        If the user was invited to the room, but had not joined, this call
+        serves to reject the invite.
+
+        The user will still be allowed to retrieve history from the room which
+        they were previously allowed to see.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier to leave.
+          required: true
+          x-example: "!nkl290a:matrix.org"
+      responses:
+        200:
+          description: |-
+            The room has been left.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership
+  "/rooms/{roomId}/forget":
+    post:
+      summary: Stop the requesting user remembering about a particular room.
+      description: |-
+        This API stops a user remembering about a particular room.
+
+        In general, history is a first class citizen in Matrix. After this API
+        is called, however, a user will no longer be able to retrieve history
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier to forget.
+          required: true
+          x-example: "!au1ba7o:matrix.org"
+      responses:
+        200:
+          description: |-
+            The room has been forgotten.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/list_public_rooms.yaml

@@ -0,0 +1,301 @@
+# 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 Client-Server Room Creation API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/publicRooms":
+    get:
+      summary: Lists the public rooms on the server.
+      description: |-
+        Lists the public rooms on the server.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      parameters:
+        - in: query
+          name: limit
+          type: number
+          description: |-
+            Limit the number of results returned.
+        - in: query
+          name: since
+          type: string
+          description: |-
+            A pagination token from a previous request, allowing clients to
+            get the next (or previous) batch of rooms.
+            The direction of pagination is specified solely by which token
+            is supplied, rather than via an explicit flag.
+        - in: query
+          name: server
+          type: string
+          description: |-
+            The server to fetch the public room lists from. Defaults to the
+            local server.
+      responses:
+        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
+              }
+      tags:
+        - Room discovery
+    post:
+      summary: Lists the public rooms on the server with optional filter.
+      description: |-
+        Lists the public rooms on the server, with optional filter.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          name: server
+          type: string
+          description: |-
+            The server to fetch the public room lists from. Defaults to the
+            local server.
+        - in: body
+          name: body
+          required: true
+          description: |-
+            Options for which rooms to return.
+          schema:
+            type: object
+            properties:
+              limit:
+                type: number
+                description: |-
+                  Limit the number of results returned.
+              since:
+                type: string
+                description: |-
+                  A pagination token from a previous request, allowing clients
+                  to get the next (or previous) batch of rooms.  The direction
+                  of pagination is specified solely by which token is supplied,
+                  rather than via an explicit flag.
+              filter:
+                type: object
+                title: "Filter"
+                description: |-
+                  Filter to apply to the results.
+                properties:
+                    generic_search_term:
+                      type: string
+                      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"}}
+      responses:
+        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
+              }
+      tags:
+        - Room discovery

api/client-server/login.yaml

@@ -0,0 +1,142 @@
+# 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 Client-Server Registration and Login 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:
+  "/login":
+    post:
+      summary: Authenticates the user.
+      description: |-
+        Authenticates the user, and issues an access token they can
+        use to authorize themself in subsequent requests.
+
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        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`_.
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "type": "m.login.password",
+                "user": "cheeky_monkey",
+                "password": "ilovebananas",
+                "initial_device_display_name": "Jungle Phone"
+              }
+            properties:
+              type:
+                type: string
+                enum: ["m.login.password", "m.login.token"]
+                description: The login type being used.
+              user:
+                type: string
+                description: The fully qualified user ID or just local part of the user ID, to log in.
+              medium:
+                type: string
+                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.
+              address:
+                type: string
+                description: Third party identifier for the user.
+              password:
+                type: string
+                description: |-
+                  Required when ``type`` is ``m.login.password``. The user's
+                  password.
+              token:
+                type: string
+                description: |-
+                  Required when ``type`` is ``m.login.token``. The login token.
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
+            required: ["type"]
+
+      responses:
+        200:
+          description: The user has been authenticated.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The fully-qualified Matrix ID that has been registered.
+              access_token:
+                type: string
+                description: |-
+                  An access token for the account.
+                  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.
+              device_id:
+                type: string
+                description: |-
+                  ID of the logged-in device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+        400:
+          description: |-
+            Part of the request was invalid. For example, the login type may not be recognised.
+          examples:
+            application/json: |-
+              {
+                  "errcode": "M_UNKNOWN",
+                  "error": "Bad login type."
+              }
+        403:
+          description: |-
+            The login attempt failed. For example, the password may have been incorrect.
+          examples:
+            application/json: |-
+              {"errcode": "M_FORBIDDEN"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Session management

api/client-server/logout.yaml

@@ -0,0 +1,45 @@
+# 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 Client-Server Registration and Login 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:
+  "/logout":
+    post:
+      summary: Invalidates a user access token
+      description: |-
+        Invalidates an existing access token, so that it can no longer be used for
+        authorization.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The access token used in the request was succesfully invalidated.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - Session management

api/client-server/message_pagination.yaml

@@ -0,0 +1,160 @@
+# 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 Client-Server Rooms 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}/messages":
+    get:
+      summary: Get a list of events for this room
+      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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get events from.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: query
+          type: string
+          name: from
+          description: |-
+            The token to start returning events from. This token can be obtained
+            from a ``prev_batch`` token returned for each room by the sync API,
+            or from a ``start`` or ``end`` token returned by a previous request
+            to this endpoint.
+          required: true
+          x-example: "s345_678_333"
+        - in: query
+          type: string
+          name: to
+          description: |-
+            The token to stop returning events at. This token can be obtained from
+            a ``prev_batch`` token returned for each room by the sync endpoint,
+            or from a ``start`` or ``end`` token returned by a previous request to
+            this endpoint.
+          required: false
+        - in: query
+          type: string
+          enum: ["b", "f"]
+          name: dir
+          description: |-
+            The direction to return events from.
+          required: true
+          x-example: "b"
+        - in: query
+          type: integer
+          name: limit
+          description: |-
+            The maximum number of events to return. Default: 10.
+          x-example: "3"
+        - in: query
+          type: string
+          name: filter
+          description: |-
+            A JSON RoomEventFilter to filter returned events with.
+          x-example: |-
+            {"contains_url":true}
+      responses:
+        200:
+          description: A list of messages with a new token to request more.
+          schema:
+            type: object
+            description: A list of messages with a new token to request more.
+            properties:
+              start:
+                type: string
+                description: |-
+                  The token the pagination starts from. If ``dir=b`` this will be
+                  the token supplied in ``from``.
+              end:
+                type: string
+                description: |-
+                  The token the pagination ends at. If ``dir=b`` this token should
+                  be used again to request even earlier events.
+              chunk:
+                type: array
+                description: |-
+                  A list of room events.
+                items:
+                  type: object
+                  title: RoomEvent
+          examples:
+            application/json: |-
+              {
+                "start": "t47429-4392820_219380_26003_2265",
+                "end": "t47409-4357353_219380_26003_2265",
+                "chunk": [
+                  {
+                    "origin_server_ts": 1444812213737,
+                    "sender": "@alice:example.com",
+                    "event_id": "$1444812213350496Caaaa:example.com",
+                    "content": {
+                      "body": "hello world",
+                      "msgtype":"m.text"
+                    },
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.message",
+                    "age": 1042
+                  },
+                  {
+                    "origin_server_ts": 1444812194656 ,
+                    "sender": "@bob:example.com",
+                    "event_id": "$1444812213350496Cbbbb:example.com",
+                    "content": {
+                      "body": "the world is big",
+                      "msgtype":"m.text"
+                    },
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.message",
+                    "age": 20123
+                  },
+                  {
+                    "origin_server_ts": 1444812163990,
+                    "sender": "@bob:example.com",
+                    "event_id": "$1444812213350496Ccccc:example.com",
+                    "content": {
+                      "name": "New room name"
+                    },
+                    "prev_content": {
+                      "name": "Old room name"
+                    },
+                    "state_key": "",
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.name",
+                    "age": 50789
+                  }
+                ]
+              }
+        403:
+          description: >
+            You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/notifications.yaml

@@ -0,0 +1,142 @@
+# 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 Client-Server Notifications 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:
+  "/notifications":
+    get:
+      summary: Gets a list of events that the user has been notified about
+      description: |-
+        This API is used to paginate through the list of events that the
+        user has been, or would have been notified about.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          name: from
+          description: Pagination token given to retrieve the next set of events.
+          required: false
+          x-example: "xxxxx"
+        - in: query
+          type: number
+          name: limit
+          description: Limit on the number of events to return in this request.
+          required: false
+          x-example: "20"
+        - in: query
+          name: only
+          type: string
+          description: |-
+            Allows basic filtering of events returned. Supply ``highlight``
+            to return only events where the notification had the highlight
+            tweak set.
+          required: false
+          x-example: "highlight"
+      responses:
+        200:
+          description: A batch of events is being returned
+          examples:
+            application/json: |-
+              {
+                "next_token": "abcdef",
+                "notifications": [
+                  {
+                    "actions": [
+                      "notify"
+                    ],
+                    "profile_tag": "hcbvkzxhcvb",
+                    "read": true,
+                    "room_id": "!abcdefg:example.com",
+                    "ts": 1475508881945,
+                    "event": {
+                      "sender": "@alice:example.com",
+                      "type": "m.room.message",
+                      "age": 124524,
+                      "txn_id": "1234",
+                      "content": {
+                        "body": "I am a fish",
+                        "msgtype": "m.text"
+                      },
+                      "origin_server_ts": 1417731086797,
+                      "event_id": "$74686972643033:example.com"
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+            required: ["notifications"]
+            properties:
+              next_token:
+                type: string
+                description: |-
+                  The token to supply in the ``from`` param of the next
+                  ``/notifications`` request in order to request more
+                  events. If this is absent, there are no more results.
+              notifications:
+                type: array
+                items:
+                  type: object
+                  required: ["actions", "event", "read", "room_id", "ts"]
+                  title: Notification
+                  properties:
+                    actions:
+                      type: array
+                      description: |-
+                        The action(s) to perform when the conditions for this rule are met.
+                        See `Push Rules: API`_.
+                      items:
+                        type:
+                        - object
+                        - string
+                    event:
+                      type: object
+                      title: Event
+                      description: The Event object for the event that triggered the notification.
+                      allOf:
+                        - "$ref": "definitions/event.yaml"
+                    profile_tag:
+                      type: string
+                      description: The profile tag of the rule that matched this event.
+                    read:
+                      type: boolean
+                      description: |-
+                        Indicates whether the user has sent a read receipt indicating
+                        that they have read this message.
+                    room_id:
+                      type: string
+                      description: The ID of the room in which the event was posted.
+                    ts:
+                      type: integer
+                      description: |-
+                        The unix timestamp at which the event notification was sent,
+                        in milliseconds.
+                description: The list of events that triggered notifications.
+      tags:
+        - Push notifications

api/client-server/old_sync.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Sync API"
+  title: "Matrix Client-Server Sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/events":
     get:
@@ -24,13 +33,20 @@ paths:
       description: |-
         This will listen for new events and return them to the caller. This will
         block until an event is received, or until the ``timeout`` is reached.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        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>`_.
       security:
         - accessToken: []
       parameters:
         - in: query
           type: string
           name: from
-          description: The token to stream from.
+          description: |-
+            The token to stream from. This token is either from a previous
+            request to this API or from the initial sync API.
           required: false
           x-example: "s3456_9_0"
         - in: query
@@ -39,16 +55,6 @@ paths:
           description: The maximum time in milliseconds to wait for an event.
           required: false
           x-example: "35000"
-        - in: query
-          type: string
-          name: archived
-          description: |-
-            Whether to include rooms that the user has left. If absent then
-            only rooms that the user has been invited to or has joined are
-            included. If set to "true" then rooms that the user has left are
-            included as well.
-          required: false
-          x-example: "true"
       responses:
         200:
           description: "The events received, which may be none."
@@ -68,7 +74,7 @@ paths:
                     "origin_server_ts": 1432804485886,
                     "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                     "type": "m.room.message",
-                    "user_id": "@bob:localhost"
+                    "sender": "@bob:localhost"
                   }
                 ]
               }
@@ -78,29 +84,37 @@ paths:
               start:
                 type: string
                 description: |-
-                  A token which correlates to the first value in ``chunk``. Used
-                  for pagination.
+                  A token which correlates to the first value in ``chunk``. This
+                  is usually the same token supplied to ``from=``.
               end:
                 type: string
                 description: |-
-                  A token which correlates to the last value in ``chunk``. Used
-                  for pagination.
+                  A token which correlates to the last value in ``chunk``. This
+                  token should be used in the next request to ``/events``.
               chunk:
                 type: array
                 description: "An array of events."
                 items:
                   type: object
-                  title: RoomEvent
+                  title: Event
                   allOf:
-                   - "$ref": "core-event-schema/room_event.json"
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
         400:
           description: "Bad pagination ``from`` parameter."
+      tags:
+        - Room participation
+      deprecated: true
   "/initialSync":
     get:
       summary: Get the user's current state.
       description: |-
         This returns the full state for this user, with an optional limit on the
         number of messages per room to return.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        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>`_.
       security:
         - accessToken: []
       parameters:
@@ -110,6 +124,16 @@ paths:
           description: The maximum number of messages to return for each room.
           required: false
           x-example: "2"
+        - in: query
+          type: boolean
+          name: archived
+          description: |-
+            Whether to include rooms that the user has left. If ``false`` then
+            only rooms that the user has been invited to or has joined are
+            included. If set to ``true`` then rooms that the user has left are
+            included as well. By default this is ``false``.
+          required: false
+          x-example: "true"
       responses:
         200:
           description: The user's current state.
@@ -129,6 +153,14 @@ paths:
                           "type": "m.presence"
                       }
                   ],
+                  "account_data": [
+                    {
+                      "type": "org.example.custom.config",
+                      "content": {
+                        "custom_config_key": "custom_config_value"
+                      }
+                    }
+                  ],
                   "rooms": [
                       {
                           "membership": "join",
@@ -144,7 +176,7 @@ paths:
                                       "origin_server_ts": 1432804485886,
                                       "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                       "type": "m.room.message",
-                                      "user_id": "@alice:localhost"
+                                      "sender": "@alice:localhost"
                                   },
                                   {
                                       "age": 343511809,
@@ -156,7 +188,7 @@ paths:
                                       "origin_server_ts": 1432804487480,
                                       "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                       "type": "m.room.message",
-                                      "user_id": "@bob:localhost"
+                                      "sender": "@bob:localhost"
                                   }
                               ],
                               "end": "s3456_9_0",
@@ -174,13 +206,12 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.join_rules",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 6547561012,
                                   "content": {
                                       "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                                      "displayname": null,
                                       "membership": "join"
                                   },
                                   "event_id": "$1426600438280zExKY:localhost",
@@ -189,7 +220,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "@alice:localhost",
                                   "type": "m.room.member",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 7148267200,
@@ -201,7 +232,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.create",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               },
                               {
                                   "age": 1622568720,
@@ -216,7 +247,7 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "@bob:localhost",
                                   "type": "m.room.member",
-                                  "user_id": "@bob:localhost"
+                                  "sender": "@bob:localhost"
                               },
                               {
                                   "age": 7148267004,
@@ -240,10 +271,22 @@ paths:
                                   "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                                   "state_key": "",
                                   "type": "m.room.power_levels",
-                                  "user_id": "@alice:localhost"
+                                  "sender": "@alice:localhost"
                               }
                           ],
-                          "visibility": "private"
+                          "visibility": "private",
+                          "account_data": [
+                            {
+                              "type": "m.tag",
+                              "content": {"tags": {"work": {"order": 1}}}
+                            },
+                            {
+                              "type": "org.example.custom.room.config",
+                              "content": {
+                                "custom_config_key": "custom_config_value"
+                              }
+                            }
+                          ]
                       }
                   ]
               }
@@ -263,7 +306,7 @@ paths:
                   type: object
                   title: Event
                   allOf:
-                   - "$ref": "core-event-schema/event.json"
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
               rooms:
                 type: array
                 items:
@@ -282,7 +325,7 @@ paths:
                         title: "InviteEvent"
                         description: "The invite event if ``membership`` is ``invite``"
                         allOf:
-                          - "$ref": "v1-event-schema/m.room.member"
+                          - "$ref": "definitions/event-schemas/schema/m.room.member"
                     messages:
                       type: object
                       title: PaginationChunk
@@ -310,7 +353,7 @@ paths:
                             type: object
                             title: RoomEvent
                             allOf:
-                              - "$ref": "core-event-schema/room_event.json"
+                              - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
                       required: ["start", "end", "chunk"]
                     state:
                       type: array
@@ -323,23 +366,48 @@ paths:
                         title: StateEvent
                         type: object
                         allOf:
-                          - "$ref": "core-event-schema/state_event.json"
+                          - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
                     visibility:
                       type: string
                       enum: ["private", "public"]
                       description: |-
                         Whether this room is visible to the ``/publicRooms`` API
                         or not."
+                    account_data:
+                      type: array
+                      description: |-
+                        The private data that this user has attached to
+                        this room.
+                      items:
+                        title: Event
+                        type: object
+                        allOf:
+                          - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
                   required: ["room_id", "membership"]
+              account_data:
+                type: array
+                description: |-
+                  The global private data created by this user.
+                items:
+                  title: Event
+                  type: object
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
             required: ["end", "rooms", "presence"]
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - Room participation
+      deprecated: true
   "/events/{eventId}":
     get:
       summary: Get a single event by event ID.
       description: |-
         Get a single event based on ``event_id``. You must have permission to
         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.
       security:
         - accessToken: []
       parameters:
@@ -359,13 +427,16 @@ paths:
                   "body": "Hello world!",
                   "msgtype": "m.text"
                 },
-                "room_id:": "!wfgy43Sg4a:matrix.org",
-                "user_id": "@bob:matrix.org",
+                "room_id": "!wfgy43Sg4a:matrix.org",
+                "sender": "@bob:matrix.org",
                 "event_id": "$asfDuShaf7Gafaw:matrix.org",
                 "type": "m.room.message"
               }
           schema:
             allOf:
-              - "$ref": "core-event-schema/event.json"
+              - "$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
+      deprecated: true

api/client-server/peeking_events.yaml

@@ -0,0 +1,114 @@
+# 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 Client-Server Sync Guest 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:
+  "/events":
+    get:
+      summary: Listen on the event stream.
+      description: |-
+        This will listen for new events related to a particular room and return
+        them to the caller. This will block until an event is received, or until
+        the ``timeout`` is reached.
+
+        This API is the same as the normal ``/events`` endpoint, but can be
+        called by users who have not joined the room.
+
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          name: from
+          description: |-
+            The token to stream from. This token is either from a previous
+            request to this API or from the initial sync API.
+          required: false
+          x-example: "s3456_9_0"
+        - in: query
+          type: integer
+          name: timeout
+          description: The maximum time in milliseconds to wait for an event.
+          required: false
+          x-example: "35000"
+        - in: query
+          type: string
+          name: room_id
+          description: |-
+            The room ID for which events should be returned.
+          x-example:
+            - "!somewhere:over.the.rainbow"
+      responses:
+        200:
+          description: "The events received, which may be none."
+          examples:
+            application/json: |-
+              {
+                "start": "s3456_9_0",
+                "end": "s3457_9_0",
+                "chunk": [
+                  {
+                    "age": 32,
+                    "content": {
+                        "body": "incoming message",
+                        "msgtype": "m.text"
+                    },
+                    "event_id": "$14328055551tzaee:localhost",
+                    "origin_server_ts": 1432804485886,
+                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                    "type": "m.room.message",
+                    "sender": "@bob:localhost"
+                  }
+                ]
+              }
+          schema:
+            type: object
+            properties:
+              start:
+                type: string
+                description: |-
+                  A token which correlates to the first value in ``chunk``. This
+                  is usually the same token supplied to ``from=``.
+              end:
+                type: string
+                description: |-
+                  A token which correlates to the last value in ``chunk``. This
+                  token should be used in the next request to ``/events``.
+              chunk:
+                type: array
+                description: "An array of events."
+                items:
+                  type: object
+                  title: Event
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+        400:
+          description: "Bad pagination ``from`` parameter."
+        # No tags to exclude this from the swagger UI - use the normal version instead.

api/client-server/presence.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Presence API"
+  title: "Matrix Client-Server Presence API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/presence/{userId}/status":
     put:
@@ -49,7 +58,7 @@ paths:
             properties:
               presence:
                 type: string
-                enum: ["online", "offline", "unavailable", "free_for_chat"]
+                enum: ["online", "offline", "unavailable"]
                 description: The new presence state.
               status_msg:
                 type: string
@@ -67,6 +76,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get this user's presence state.
       description: |-
@@ -85,15 +96,14 @@ paths:
             application/json: |-
               {
                 "presence": "unavailable",
-                "last_active_ago": 420845,
-                "status_msg": null
+                "last_active_ago": 420845
               }
           schema:
             type: object
             properties:
               presence:
                 type: string
-                enum: ["online", "offline", "unavailable", "free_for_chat"]
+                enum: ["online", "offline", "unavailable"]
                 description: This user's presence.
               last_active_ago:
                 type: integer
@@ -103,10 +113,16 @@ paths:
               status_msg:
                 type: [string, "null"]
                 description: The state message for this user if one was set.
+              currently_active:
+                type: boolean
+                description: "Whether the user is currently active"
+            required: ["presence"]
         404:
           description: |-
             There is no presence state for this user. This user may not exist or
             isn't exposing presence information to you.
+      tags:
+        - Presence
   "/presence/list/{userId}":
     post:
       summary: Add or remove users from this presence list.
@@ -161,6 +177,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Presence
     get:
       summary: Get presence events for this presence list.
       description: |-
@@ -180,8 +198,6 @@ paths:
               [
                 {
                   "content": {
-                    "avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
-                    "displayname": "Alice Margatroid",
                     "last_active_ago": 395,
                     "presence": "offline",
                     "user_id": "@alice:matrix.org"
@@ -190,11 +206,10 @@ paths:
                 },
                 {
                   "content": {
-                    "avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf",
-                    "displayname": "Marisa Kirisame",
                     "last_active_ago": 16874,
                     "presence": "online",
-                    "user_id": "@marisa:matrix.org"
+                    "user_id": "@marisa:matrix.org",
+                    "currently_active": true
                   },
                   "type": "m.presence"
                 }
@@ -205,4 +220,6 @@ paths:
               type: object
               title: PresenceEvent
               allOf:
-                - "$ref": "core-event-schema/event.json"
+                - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
+      tags:
+        - Presence

api/client-server/profile.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Profile API"
+  title: "Matrix Client-Server Profile API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/profile/{userId}/displayname":
     put:
@@ -59,6 +68,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's display name.
       description: |-
@@ -85,9 +96,11 @@ paths:
             properties:
               displayname:
                 type: string
-                description: The user's display name if they have set one.
+                description: The user's display name if they have set one, otherwise not present.
         404:
           description: There is no display name for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}/avatar_url":
     put:
       summary: Set the user's avatar URL.
@@ -129,6 +142,8 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - User data
     get:
       summary: Get the user's avatar URL.
       description: |-
@@ -155,9 +170,11 @@ paths:
             properties:
               avatar_url:
                 type: string
-                description: The user's avatar URL if they have set one.
+                description: The user's avatar URL if they have set one, otherwise not present.
         404:
           description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - User data
   "/profile/{userId}":
     get:
       summary: Get this user's profile information.
@@ -170,7 +187,7 @@ paths:
         - in: path
           type: string
           name: userId
-          description: The user whose avatar URL to get.
+          description: The user whose profile information to get.
           required: true
           x-example: "@alice:example.com"
       responses:
@@ -187,9 +204,11 @@ paths:
             properties:
               avatar_url:
                 type: string
-                description: The user's avatar URL if they have set one.
+                description: The user's avatar URL if they have set one, otherwise not present.
               displayname:
                 type: string
-                description: The user's display name if they have set one.
+                description: The user's display name if they have set one, otherwise not present.
         404:
-          description: There is no profile information for this user or this user does not exist.
+          description: There is no profile information for this user or this user does not exist.
+      tags:
+        - User data

api/client-server/pusher.yaml

@@ -1,23 +1,122 @@
+# 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 Client-Server v1 Push API"
+  title: "Matrix Client-Server Push API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
+  "/pushers":
+    get:
+      summary: Gets the current pushers for the authenticated user
+      description: |-
+          Gets all currently active pushers for the authenticated user
+      security:
+        - accessToken: []
+      responses:
+        200:
+          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"
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+            properties:
+              pushers:
+                type: array
+                title: Pushers
+                description: |-
+                  An array containing the current pushers for the user
+                items:
+                  type: object
+                  title: Pusher
+                  properties:
+                    pushkey:
+                      type: string
+                      description: |-
+                        This is a unique identifier for this pusher. See `/set` for
+                        more detail.
+                        Max length, 512 bytes.
+                    kind:
+                      type: string
+                      description: |-
+                        The kind of pusher. ``"http"`` is a pusher that
+                        sends HTTP pokes.
+                    app_id:
+                      type: string
+                      description: |-
+                        This is a reverse-DNS style identifier for the application.
+                        Max length, 64 chars.
+                    app_display_name:
+                      type: string
+                      description: |-
+                        A string that will allow the user to identify what application
+                        owns this pusher.
+                    device_display_name:
+                      type: string
+                      description: |-
+                        A string that will allow the user to identify what device owns
+                        this pusher.
+                    profile_tag:
+                      type: string
+                      description: |-
+                        This string determines which set of device specific rules this
+                        pusher executes.
+                    lang:
+                      type: string
+                      description: |-
+                        The preferred language for receiving notifications (e.g. 'en'
+                        or 'en-US')
+                    data:
+                      type: object
+                      description: |-
+                        A dictionary of information for the pusher implementation
+                        itself.
+                      title: PusherData
+                      properties:
+                        url:
+                          type: string
+                          description: |-
+                            Required if ``kind`` is ``http``. The URL to use to send
+                            notifications to.
+      tags:
+        - Push notifications
   "/pushers/set":
     post:
       summary: Modify a pusher for this user on the homeserver.
@@ -40,8 +139,8 @@ paths:
                 "kind": "http",
                 "app_display_name": "Mat Rix",
                 "device_display_name": "iPhone 9",
+                "profile_tag": "xxyyzz",
                 "app_id": "com.example.app.ios",
-                "profile_tag": "4bea66906d0111e59d70feff819cdc9f",
                 "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
                 "data": {
                   "url": "https://push-gateway.location.here"
@@ -60,21 +159,9 @@ paths:
                   Max length, 512 bytes.
               kind:
                 type: string
-                enum: ["http", null]
                 description: |-
                   The kind of pusher to configure. ``"http"`` makes a pusher that
                   sends HTTP pokes. ``null`` deletes the pusher.
-              profile_tag:
-                type: string
-                description: |-
-                  This is a string that determines what set of device rules will
-                  be matched when evaluating push rules for this pusher. It is
-                  an arbitrary string. Multiple devices may use the same
-                  ``profile_tag``. It is advised that when an app's data is
-                  copied or restored to a different device, this value remain
-                  the same. Client apps should offer ways to change the
-                  ``profile_tag``, optionally copying rules from the old
-                  profile tag. Max length, 32 bytes.
               app_id:
                 type: string
                 description: |-
@@ -92,6 +179,11 @@ paths:
                 description: |-
                   A string that will allow the user to identify what device owns
                   this pusher.
+              profile_tag:
+                type: string
+                description: |-
+                  This string determines which set of device specific rules this
+                  pusher executes.
               lang:
                 type: string
                 description: |-
@@ -103,6 +195,7 @@ paths:
                   A dictionary of information for the pusher implementation
                   itself. If ``kind`` is ``http``, this should contain ``url``
                   which is the URL to use to send notifications to.
+                title: PusherData
                 properties:
                   url:
                     type: string
@@ -114,10 +207,10 @@ paths:
                 description: |-
                   If true, the homeserver should add another pusher with the
                   given pushkey and App ID in addition to any others with
-                  different user IDs. Otherwise, the Home Server must remove any
+                  different user IDs. Otherwise, the homeserver must remove any
                   other pushers with the same App ID and pushkey for different
                   users. The default is ``false``.
-            required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
+            required: ['kind', 'app_id', 'app_display_name',
                 'device_display_name', 'pushkey', 'lang', 'data']
       responses:
         200:
@@ -141,4 +234,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Push notifications

api/client-server/pushrules.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Push Rules API"
+  title: "Matrix Client-Server Push Rules API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/pushrules/":
     get:
@@ -33,31 +42,18 @@ paths:
           description: All the push rulesets for this user.
           schema:
             type: object
-            required: ["device", "global"]
+            required: ["global"]
             properties:
-              device:
-                type: object
-                title: Devices
-                description: A dictionary of profile tags to rulesets.
-                additionalProperties:
-                    x-pattern: "$PROFILE_TAG"
-                    type: object
-                    description: The ruleset for this profile tag.
-                    title: Ruleset
-                    allOf: [
-                      "$ref": "definitions/push_ruleset.json"
-                    ]
               global:
                 type: object
                 description: The global ruleset.
                 title: Ruleset
                 allOf: [
-                  "$ref": "definitions/push_ruleset.json"
+                  "$ref": "definitions/push_ruleset.yaml"
                 ]
           examples:
             application/json: |-
               {
-                "device": {},
                 "global": {
                     "content": [
                         {
@@ -245,6 +241,8 @@ paths:
                     ]
                 }
               }
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}":
     get:
       summary: Retrieve a push rule.
@@ -259,13 +257,12 @@ paths:
           required: true
           x-example: "global"
           description: |-
-            Either ``global`` or ``device/<profile_tag>`` to specify global
-            rules or device rules for the given ``profile_tag``.
+            ``global`` to specify global rules.
         - in: path
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -273,7 +270,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
       responses:
@@ -287,16 +284,19 @@ paths:
                 "actions": [
                     "dont_notify"
                 ],
-                "rule_id": "#spam:matrix.org",
-                "enabled": true
+                "pattern": "cake*lie",
+                "rule_id": "nocake",
+                "enabled": true,
+                "default": false
               }
           schema:
             type: object
             description: The push rule.
-            title: PushRule
             allOf: [
-              "$ref": "definitions/push_rule.json"
+              "$ref": "definitions/push_rule.yaml"
             ]
+      tags:
+        - Push notifications
     delete:
       summary: Delete a push rule.
       description: |-
@@ -310,13 +310,12 @@ paths:
           required: true
           x-example: "global"
           description: |-
-            Either ``global`` or ``device/<profile_tag>`` to specify global
-            rules or device rules for the given ``profile_tag``.
+            ``global`` to specify global rules.
         - in: path
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -324,7 +323,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
       responses:
@@ -335,6 +334,8 @@ paths:
               {}
           schema:
             type: object  # empty json object
+      tags:
+        - Push notifications
     put:
       summary: Add or change a push rule.
       description: |-
@@ -350,13 +351,12 @@ paths:
           required: true
           x-example: "global"
           description: |-
-            Either ``global`` or ``device/<profile_tag>`` to specify global
-            rules or device rules for the given ``profile_tag``.
+            ``global`` to specify global rules.
         - in: path
           type: string
           name: kind
           required: true
-          x-example: room
+          x-example: content
           enum: ["override", "underride", "sender", "room", "content"]
           description: |
             The kind of rule
@@ -364,7 +364,7 @@ paths:
           type: string
           name: ruleId
           required: true
-          x-example: "#spam:example.com"
+          x-example: "nocake"
           description: |
             The identifier for the rule.
         - in: query
@@ -374,7 +374,8 @@ paths:
           x-example: someRuleId
           description: |-
             Use 'before' with a ``rule_id`` as its value to make the new rule the
-            next-most important rule with respect to the given rule.
+            next-most important rule with respect to the given user defined rule.
+            It is not possible to add a rule relative to a predefined server rule.
         - in: query
           type: string
           name: after
@@ -382,7 +383,8 @@ paths:
           x-example: anotherRuleId
           description: |-
             This makes the new rule the next-less important rule relative to the
-            given rule.
+            given user defined rule. It is not possible to add a rule relative
+            to a predefined server rule.
         - in: body
           name: pushrule
           description: |-
@@ -410,11 +412,14 @@ paths:
                 description: |-
                   The conditions that must hold true for an event in order for a
                   rule to be applied to an event. A rule with no conditions
-                  always matches.
+                  always matches. Only applicable to ``underride`` and ``override`` rules.
                 items:
                   type: object
-                  title: conditions
-                  allOf: [ "$ref": "definitions/push_condition.json" ]
+                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
+              pattern:
+                type: string
+                description: |-
+                  Only applicable to ``content`` rules. The glob-style pattern to match against.
             required: ["actions"]
       responses:
         200:
@@ -438,13 +443,116 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Push notifications
   "/pushrules/{scope}/{kind}/{ruleId}/enabled":
+    get:
+      summary: "Get whether a push rule is enabled"
+      description:
+        This endpoint gets whether the specified push rule is enabled.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: cake
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: nocake
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: Whether the push rule is enabled.
+          examples:
+            application/json: |-
+              {
+                "enabled": true
+              }
+          schema:
+            type: object
+            properties:
+              enabled:
+                type: boolean
+                description: Whether the push rule is enabled or not.
+            required: ["enabled"]
     put:
       summary: "Enable or disable a push rule."
       description: |-
         This endpoint allows clients to enable or disable the specified push rule.
       security:
         - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "nocake"
+          description: |
+            The identifier for the rule.
+        - in: body
+          name: body
+          description: |
+            Whether the push rule is enabled or not.
+          required: true
+          schema:
+            type: object
+            properties:
+              enabled:
+                type: boolean
+                description: Whether the push rule is enabled or not.
+            required: ["enabled"]
+            example: |-
+              {
+                "enabled": true
+              }
+      responses:
+        200:
+          description: The push rule was enabled or disabled.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+      tags:
+        - Push notifications
+  "/pushrules/{scope}/{kind}/{ruleId}/actions":
+    get:
+      summary: "The actions for a push rule"
+      description:
+        This endpoint get the actions for the specified push rule.
+      security:
+        - accessToken: []
       parameters:
         - in: path
           type: string
@@ -454,6 +562,53 @@ paths:
           description: |-
             Either ``global`` or ``device/<profile_tag>`` to specify global
             rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: nocake
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: The actions for this push rule.
+          examples:
+            application/json: |-
+              {
+                "actions": ["notify"]
+              }
+          schema:
+            type: object
+            properties:
+              actions:
+                type: array
+                description:  The action(s) to perform for this rule.
+                items:
+                  type: string
+            required: ["actions"]
+    put:
+      summary: "Set the actions for a push rule."
+      description: |-
+        This endpoint allows clients to change the actions of a push rule.
+        This can be used to change the actions of builtin rules.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
         - in: path
           type: string
           name: kind
@@ -470,19 +625,32 @@ paths:
           description: |
             The identifier for the rule.
         - in: body
-          name: <body>
+          name: body
           description: |
-            Whether the push rule is enabled or not.
+            The action(s) to perform when the conditions for this rule are met.
           required: true
           schema:
-            type: boolean
+            type: object
+            properties:
+              actions:
+                type: array
+                description: The action(s) to perform for this rule.
+                items:
+                  type: string
+                  enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
+                  # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
+            required: ["actions"]
             example: |-
-              true
+              {
+                "actions": ["notify"]
+              }
       responses:
         200:
-          description: The push rule was enabled or disabled.
+          description: The actions for the push rule were set.
           examples:
             application/json: |-
               {}
           schema:
-            type: object  # empty json object
+            type: object
+      tags:
+        - Push notifications

api/client-server/receipts.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v2 Receipts API"
+  title: "Matrix Client-Server Receipts API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/receipt/{receiptType}/{eventId}":
     post:
@@ -67,3 +76,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
+      tags:
+        - Room participation

api/client-server/redaction.yaml

@@ -0,0 +1,93 @@
+# 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 Client-Server message redaction 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}/redact/{eventId}/{txnId}":
+    put:
+      summary: Strips all non-integrity-critical information out of an event.
+      description: |-
+        Strips all information out of an event which isn't critical to the
+        integrity of the server-side representation of the room.
+
+        This cannot be undone.
+
+        Users may redact their own events, and any user with a power level
+        greater than or equal to the `redact` power level of the room may
+        redact events there.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room from which to redact the event.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The ID of the event to redact
+          required: true
+          x-example: "bai2b1i9:matrix.org"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "37"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "reason": "Indecent material"
+              }
+            properties:
+              reason:
+                type: string
+                description: The reason for the event being redacted.
+      responses:
+        200:
+          description: "An ID for the redaction event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwQidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/registration.yaml

@@ -0,0 +1,347 @@
+# 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 Client-Server Registration API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/register":
+    post:
+      summary: Register for an account on this homeserver.
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Register for an account on this homeserver.
+
+        There are two kinds of user account:
+
+        - `user` accounts. These accounts may use the full API described in this specification.
+
+        - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
+
+        If registration is successful, this endpoint will issue an access token
+        the client can use to authorize itself in subsequent requests.
+
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        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`_.
+      parameters:
+        - in: query
+          name: kind
+          type: string
+          # swagger-UI overrides the default with the example, so better make the
+          # example the default.
+          x-example: user
+          required: false
+          default: user
+          enum:
+            - guest
+            - user
+          description: The kind of account to register. Defaults to `user`.
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API. Note that this
+                    information is *not* used to define how the registered user
+                    should be authenticated, but is instead used to
+                    authenticate the ``register`` call itself. It should be
+                    left empty, or omitted, unless an earlier call returned an
+                    response with status code 401.
+                "$ref": "definitions/auth_data.yaml"
+              bind_email:
+                type: boolean
+                description: |-
+                  If true, the server binds the email used for authentication to
+                  the Matrix ID with the ID Server.
+                example: false
+              username:
+                type: string
+                description: |-
+                  The local part of the desired Matrix ID. If omitted,
+                  the homeserver MUST generate a Matrix ID local part.
+                example: cheeky_monkey
+              password:
+                type: string
+                description: The desired password for the account.
+                example: ilovebananas
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+                example: GHTYAJCE
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
+                example: Jungle Phone
+      responses:
+        200:
+          description: The account has been registered.
+          examples:
+            application/json: |-
+              {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The fully-qualified Matrix ID that has been registered.
+              access_token:
+                type: string
+                description: |-
+                  An access token for the account.
+                  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.
+              device_id:
+                type: string
+                description: |-
+                  ID of the registered device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+        400:
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * ``M_USER_IN_USE`` : The desired user ID is already taken.
+            * ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name.
+            * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
+              claimed by an application service.
+
+            These errors may be returned at any stage of the registration process,
+            including after authentication if the requested user ID was registered
+            whilst the client was performing authentication.
+
+            Homeservers MUST perform the relevant checks and return these codes before
+            performing User-Interactive Authentication, although they may also return
+            them after authentication is completed if, for example, the requested user ID
+            was registered whilst the client was performing authentication.
+          examples:
+            application/json: |-
+              {
+                  "errcode": "M_USER_IN_USE",
+                  "error": "Desired user ID is already taken."
+              }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data
+  "/register/email/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given email address for the purpose of registering an account
+      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
+        further information.
+      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"
+              email:
+                type: string
+                description: The email address
+                example: "example@example.com"
+              send_attempt:
+                type: number
+                description: Used to distinguish protocol level retries from requests to re-send the email.
+                example: "1"
+            required: ["client_secret", "email", "send_attempt"]
+      responses:
+        200:
+          description: |-
+            An email has been sent to the specified address.
+            Note that this may be an email containing the validation token or it may be informing
+            the user of an error.
+          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 email address is already registered to an account on this server.
+              However, if the home server has the ability to send email, it is recommended that the server
+              instead send an email to the user with instructions on how to reset their password.
+              This prevents malicious parties from being able to determine if a given email address
+              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:
+            type: object
+  "/account/password":
+    post:
+      summary: "Changes a user's password."
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              new_password:
+                type: string
+                description: The new password for the account.
+                example: "ihatebananas"
+              auth:
+                description: |-
+                  Additional authentication information for the user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+            required: ["new_password"]
+      responses:
+        200:
+          description: The password has been changed.
+          examples:
+            application/json: "{}"
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data
+  "/account/password/email/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given email address for the purpose of resetting a user's password
+      description: |-
+        Proxies the identity server API ``validate/email/requestToken``, but
+        first checks that the given email address **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/email/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
+        email to the given address prompting the user to create an account.
+        `M_THREEPID_IN_USE` may not be returned.
+
+        .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
+
+        .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
+      responses:
+        200:
+          description: An email was sent to the given address
+  "/account/deactivate":
+    post:
+      summary: "Deactivate a user's account."
+      description: |-
+        Deactivate the user's account, removing all ability for the user to
+        login again.
+
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                  Additional authentication information for the user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+      responses:
+        200:
+          description: The account has been deactivated.
+          examples:
+            application/json: "{}"
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data

api/client-server/room_initial_sync.yaml

@@ -0,0 +1,233 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Rooms 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}/initialSync":
+    get:
+      summary: Snapshot the current state of a room and its most recent messages.
+      description: |-
+        Get a copy of the current state and the most recent messages in a room.
+
+        This endpoint was deprecated in r0 of this specification. There is no
+        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>`_.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get the data.
+          required: true
+          x-example: "!636q39766251:example.com"
+      responses:
+        200:
+          description: The current state of the room
+          examples:
+            application/json: |-
+              {
+                "membership": "join",
+                "messages": {
+                  "chunk": [
+                    {
+                      "age": 343513403,
+                      "content": {
+                        "body": "foo",
+                        "msgtype": "m.text"
+                      },
+                      "event_id": "$14328044851tzTJS:example.com",
+                      "origin_server_ts": 1432804485886,
+                      "room_id": "!636q39766251:example.com",
+                      "type": "m.room.message",
+                      "sender": "@alice:example.com"
+                    },
+                    {
+                      "age": 343511809,
+                      "content": {
+                        "body": "bar",
+                        "msgtype": "m.text"
+                      },
+                      "event_id": "$14328044872spjFg:example.com",
+                      "origin_server_ts": 1432804487480,
+                      "room_id": "!636q39766251:example.com",
+                      "type": "m.room.message",
+                      "sender": "@bob:example.com"
+                    }
+                  ],
+                  "end": "s3456_9_0",
+                  "start": "t44-3453_9_0"
+                },
+                "room_id": "!636q39766251:example.com",
+                "state": [
+                  {
+                    "age": 7148266897,
+                    "content": {
+                      "join_rule": "public"
+                    },
+                    "event_id": "$14259997323TLwtb:example.com",
+                    "origin_server_ts": 1425999732392,
+                    "room_id": "!636q39766251:example.com",
+                    "state_key": "",
+                    "type": "m.room.join_rules",
+                    "sender": "@alice:example.com"
+                  },
+                  {
+                    "age": 6547561012,
+                    "content": {
+                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
+                      "membership": "join"
+                    },
+                    "event_id": "$1426600438280zExKY:example.com",
+                    "membership": "join",
+                    "origin_server_ts": 1426600438277,
+                    "room_id": "!636q39766251:example.com",
+                    "state_key": "@alice:example.com",
+                    "type": "m.room.member",
+                    "sender": "@alice:example.com"
+                  },
+                  {
+                    "age": 7148267200,
+                    "content": {
+                        "creator": "@alice:example.com"
+                    },
+                    "event_id": "$14259997320KhbwJ:example.com",
+                    "origin_server_ts": 1425999732089,
+                    "room_id": "!636q39766251:example.com",
+                    "state_key": "",
+                    "type": "m.room.create",
+                    "sender": "@alice:example.com"
+                  },
+                  {
+                    "age": 1622568720,
+                    "content": {
+                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
+                        "displayname": "Bob",
+                        "membership": "join"
+                    },
+                    "event_id": "$1431525430134MxlLX:example.com",
+                    "origin_server_ts": 1431525430569,
+                    "replaces_state": "$142652023736BSXcM:example.com",
+                    "room_id": "!636q39766251:example.com",
+                    "state_key": "@bob:example.com",
+                    "type": "m.room.member",
+                    "sender": "@bob:example.com"
+                  },
+                  {
+                    "age": 7148267004,
+                    "content": {
+                      "ban": 50,
+                      "events": {
+                        "m.room.name": 100,
+                        "m.room.power_levels": 100
+                      },
+                      "events_default": 0,
+                      "kick": 50,
+                      "redact": 50,
+                      "state_default": 50,
+                      "users": {
+                        "@alice:example.com": 100
+                      },
+                      "users_default": 0
+                    },
+                    "event_id": "$14259997322mqfaq:example.com",
+                    "origin_server_ts": 1425999732285,
+                    "room_id": "!636q39766251:example.com",
+                    "state_key": "",
+                    "type": "m.room.power_levels",
+                    "sender": "@alice:example.com"
+                  }
+                ],
+                "visibility": "private",
+                "account_data": [{
+                    "type": "m.tag",
+                    "content": {"tags": {"work": {"order": "1"}}}
+                }]
+              }
+          schema:
+            title: RoomInfo
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: "The ID of this room."
+              membership:
+                type: string
+                description: "The user's membership state in this room."
+                enum: ["invite", "join", "leave", "ban"]
+              messages:
+                type: object
+                title: PaginationChunk
+                description: "The pagination chunk for this room."
+                properties:
+                  start:
+                    type: string
+                    description: |-
+                      A token which correlates to the first value in ``chunk``.
+                      Used for pagination.
+                  end:
+                    type: string
+                    description: |-
+                      A token which correlates to the last value in ``chunk``.
+                      Used for pagination.
+                  chunk:
+                    type: array
+                    description: |-
+                      If the user is a member of the room this will be a
+                      list of the most recent messages for this room. If
+                      the user has left the room this will be the
+                      messages that preceeded them leaving. This array
+                      will consist of at most ``limit`` elements.
+                    items:
+                      type: object
+                      title: RoomEvent
+                      allOf:
+                        - "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+                required: ["start", "end", "chunk"]
+              state:
+                type: array
+                description: |-
+                  If the user is a member of the room this will be the
+                  current state of the room as a list of events. If the
+                  user has left the room this will be the state of the
+                  room when they left it.
+                items:
+                  title: StateEvent
+                  type: object
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
+              visibility:
+                type: string
+                enum: ["private", "public"]
+                description: |-
+                  Whether this room is visible to the ``/publicRooms`` API
+                  or not."
+              account_data:
+                type: array
+                description: |-
+                  The private data that this user has attached to this room.
+                items:
+                  title: Event
+                  type: object
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
+            required: ["room_id"]
+        403:
+          description: >
+            You aren't a member of the room and weren't previously a
+            member of the room.
+      tags:
+        - Room participation
+      deprecated: true

api/client-server/room_send.yaml

@@ -0,0 +1,90 @@
+# 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 Client-Server message event send 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}/send/{eventType}/{txnId}":
+    put:
+      summary: Send a message event to the given room.
+      description: |-
+        This endpoint is used to send a message event to a room. Message events
+        allow access to historical events and pagination, making them suited
+        for "once-off" activity in a room.
+
+        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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to send the event to.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.message"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate an
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "msgtype": "m.text",
+                "body": "hello"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/room_state.yaml

@@ -0,0 +1,148 @@
+# 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 Client-Server state event send 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}/state/{eventType}/{stateKey}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint.  These events will be
+        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        match.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.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: "@alice:example.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            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"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state/{eventType}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint. This endpoint is
+        equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
+        with an empty `stateKey`. Previous state events with matching
+        `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.name"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                  "name": "New name for the room"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: |-
+              {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/rooms.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Rooms API"
+  title: "Matrix Client-Server Rooms API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/state/{eventType}/{stateKey}":
     get:
@@ -44,7 +53,7 @@ paths:
         - in: path
           type: string
           name: stateKey
-          description: The key of the state to look up. Defaults to the empty string.
+          description: The key of the state to look up.
           required: true
           x-example: ""
       responses:
@@ -61,7 +70,49 @@ paths:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state/{eventType}":
+    get:
+      summary: Get the state identified by the type, with the empty state key.
+      description: |-
+        Looks up the contents of a state event in a room. If the user is
+        joined to the room then the state is taken from the current
+        state of the room. If the user has left the room then the state is
+        taken from the state of the room when they left.
 
+        This looks up the state event with the empty state key.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to look up the state in.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of state to look up.
+          required: true
+          x-example: "m.room.name"
+      responses:
+        200:
+          description: The content of the state event.
+          examples:
+            application/json: |-
+              {"name": "Example room name"}
+          schema:
+            type: object
+        404:
+          description: The room has no state with the given type or key.
+        403:
+          description: >
+            You aren't a member of the room and weren't previously a
+            member of the room.
+      tags:
+        - Room participation
   "/rooms/{roomId}/state":
     get:
       summary: Get all state events in the current state of a room.
@@ -92,13 +143,12 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.join_rules",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 6547561012,
                     "content": {
                         "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                        "displayname": null,
                         "membership": "join"
                     },
                     "event_id": "$1426600438280zExKY:example.com",
@@ -107,7 +157,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@alice:example.com",
                     "type": "m.room.member",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 7148267200,
@@ -119,7 +169,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.create",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 },
                 {
                     "age": 1622568720,
@@ -134,7 +184,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@bob:example.com",
                     "type": "m.room.member",
-                    "user_id": "@bob:example.com"
+                    "sender": "@bob:example.com"
                 },
                 {
                     "age": 7148267004,
@@ -158,7 +208,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "",
                     "type": "m.room.power_levels",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                 }
               ]
           schema:
@@ -173,210 +223,13 @@ paths:
               title: StateEvent
               type: object
               allOf:
-                - "$ref": "core-event-schema/state_event.json"
-        403:
-          description: >
-            You aren't a member of the room and weren't previously a
-            member of the room.
-
-  "/rooms/{roomId}/initialSync":
-    get:
-      summary: Snapshot the current state of a room and its most recent messages.
-      description: |-
-        Get a copy of the current state and the most recent messages in a room.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room to get the data.
-          required: true
-          x-example: "!636q39766251:example.com"
-      responses:
-        200:
-          description: The current state of the room
-          examples:
-            application/json: |-
-              {
-                "membership": "join",
-                "messages": {
-                  "chunk": [
-                    {
-                      "age": 343513403,
-                      "content": {
-                        "body": "foo",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14328044851tzTJS:example.com",
-                      "origin_server_ts": 1432804485886,
-                      "room_id": "!636q39766251:example.com",
-                      "type": "m.room.message",
-                      "user_id": "@alice:example.com"
-                    },
-                    {
-                      "age": 343511809,
-                      "content": {
-                        "body": "bar",
-                        "msgtype": "m.text"
-                      },
-                      "event_id": "$14328044872spjFg:example.com",
-                      "origin_server_ts": 1432804487480,
-                      "room_id": "!636q39766251:example.com",
-                      "type": "m.room.message",
-                      "user_id": "@bob:example.com"
-                    }
-                  ],
-                  "end": "s3456_9_0",
-                  "start": "t44-3453_9_0"
-                },
-                "room_id": "!636q39766251:example.com",
-                "state": [
-                  {
-                    "age": 7148266897,
-                    "content": {
-                      "join_rule": "public"
-                    },
-                    "event_id": "$14259997323TLwtb:example.com",
-                    "origin_server_ts": 1425999732392,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.join_rules",
-                    "user_id": "@alice:example.com"
-                  },
-                  {
-                    "age": 6547561012,
-                    "content": {
-                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "displayname": null,
-                      "membership": "join"
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
-                    "type": "m.room.member",
-                    "user_id": "@alice:example.com"
-                  },
-                  {
-                    "age": 7148267200,
-                    "content": {
-                        "creator": "@alice:example.com"
-                    },
-                    "event_id": "$14259997320KhbwJ:example.com",
-                    "origin_server_ts": 1425999732089,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.create",
-                    "user_id": "@alice:example.com"
-                  },
-                  {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
-                    "type": "m.room.member",
-                    "user_id": "@bob:example.com"
-                  },
-                  {
-                    "age": 7148267004,
-                    "content": {
-                      "ban": 50,
-                      "events": {
-                        "m.room.name": 100,
-                        "m.room.power_levels": 100
-                      },
-                      "events_default": 0,
-                      "kick": 50,
-                      "redact": 50,
-                      "state_default": 50,
-                      "users": {
-                        "@alice:example.com": 100
-                      },
-                      "users_default": 0
-                    },
-                    "event_id": "$14259997322mqfaq:example.com",
-                    "origin_server_ts": 1425999732285,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.power_levels",
-                    "user_id": "@alice:example.com"
-                  }
-                ],
-                "visibility": "private"
-              }
-          schema:
-            title: RoomInfo
-            type: object
-            properties:
-              room_id:
-                type: string
-                description: "The ID of this room."
-              membership:
-                type: string
-                description: "The user's membership state in this room."
-                enum: ["invite", "join", "leave", "ban"]
-              messages:
-                type: object
-                title: PaginationChunk
-                description: "The pagination chunk for this room."
-                properties:
-                  start:
-                    type: string
-                    description: |-
-                      A token which correlates to the first value in ``chunk``.
-                      Used for pagination.
-                  end:
-                    type: string
-                    description: |-
-                      A token which correlates to the last value in ``chunk``.
-                      Used for pagination.
-                  chunk:
-                    type: array
-                    description: |-
-                      If the user is a member of the room this will be a
-                      list of the most recent messages for this room. If
-                      the user has left the room this will be the
-                      messages that preceeded them leaving. This array
-                      will consist of at most ``limit`` elements.
-                    items:
-                      type: object
-                      title: RoomEvent
-                      allOf:
-                        - "$ref": "core-event-schema/room_event.json"
-                required: ["start", "end", "chunk"]
-              state:
-                type: array
-                description: |-
-                  If the user is a member of the room this will be the
-                  current state of the room as a list of events. If the
-                  user has left the room this will be the state of the
-                  room when they left it.
-                items:
-                  title: StateEvent
-                  type: object
-                  allOf:
-                    - "$ref": "core-event-schema/state_event.json"
-              visibility:
-                type: string
-                enum: ["private", "public"]
-                description: |-
-                  Whether this room is visible to the ``/publicRooms`` API
-                  or not."
-            required: ["room_id", "membership"]
+                - "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
         403:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation
   "/rooms/{roomId}/members":
     get:
       summary: Get the m.room.member events for the room.
@@ -393,7 +246,7 @@ paths:
         200:
           description: |-
             A list of members of the room. If you are joined to the room then
-            this will be the current members of the room. If you have left te
+            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: |-
@@ -403,7 +256,6 @@ paths:
                     "age": 6547561012,
                     "content": {
                       "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "displayname": null,
                       "membership": "join"
                     },
                     "event_id": "$1426600438280zExKY:example.com",
@@ -412,7 +264,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@alice:example.com",
                     "type": "m.room.member",
-                    "user_id": "@alice:example.com"
+                    "sender": "@alice:example.com"
                   },
                   {
                     "age": 1622568720,
@@ -427,7 +279,7 @@ paths:
                     "room_id": "!636q39766251:example.com",
                     "state_key": "@bob:example.com",
                     "type": "m.room.member",
-                    "user_id": "@bob:example.com"
+                    "sender": "@bob:example.com"
                   }
                 ]
               }
@@ -440,9 +292,10 @@ paths:
                   title: MemberEvent
                   type: object
                   allOf:
-                    - "$ref": "v1-event-schema/m.room.member"
+                    - "$ref": "definitions/event-schemas/schema/m.room.member"
         403:
           description: >
             You aren't a member of the room and weren't previously a
             member of the room.
-
+      tags:
+        - Room participation

api/client-server/search.yaml

@@ -0,0 +1,344 @@
+# 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 Client-Server Search 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:
+  "/search":
+    post:
+      summary: Perform a server-side search.
+      description: |-
+        Performs a full text search across different categories.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          name: next_batch
+          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.
+          x-example: "YWxsCgpOb25lLDM1ODcwOA"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: |-
+              {
+                "search_categories": {
+                  "room_events": {
+                    "keys": [
+                      "content.body"
+                    ],
+                    "search_term": "martians and men"
+                  }
+                },
+                "order_by": "recent",
+                "groupings": {
+                  "group_by": [
+                    {
+                      "key": "room_id"
+                    }
+                  ]
+                }
+              }
+            properties:
+              search_categories:
+                type: object
+                title: "Categories"
+                description: Describes which categories to search in and
+                  their criteria.
+                properties:
+                  room_events:
+                    type: object
+                    title: "Room Events"
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      search_term:
+                        type: string
+                        description: The string to search events for
+                      keys:
+                        type: array
+                        items:
+                          type: string
+                          enum: ["content.body", "content.name", "content.topic"]
+                        description: The keys to search. Defaults to all.
+                      filter:
+                        type: object
+                        title: Filter
+                        description: |-
+                          This takes a `filter <https://matrix.org/docs/spec/%CLIENT_RELEASE_LABEL%/client_server.html#filtering>`_.
+                      order_by:
+                        title: "Ordering"
+                        type: string
+                        enum: ["recent", "rank"]
+                        description: "The order in which to search for results."
+                      event_context:
+                        title: "Event Context"
+                        type: object
+                        description: |-
+                          Configures whether any context for the events
+                          returned are included in the response.
+                        properties:
+                            before_limit:
+                                type: integer
+                                title: "Before limit"
+                                description: |-
+                                  How many events before the result are
+                                  returned.
+                            after_limit:
+                                type: integer
+                                title: "After limit"
+                                description: |-
+                                  How many events after the result are
+                                  returned.
+                            include_profile:
+                                type: boolean
+                                title: "Return profile information"
+                                description: |-
+                                  Requests that the server returns the
+                                  historic profile information for the users
+                                  that sent the events that were returned.
+                      include_state:
+                        type: boolean
+                        title: Include current state
+                        description: |-
+                          Requests the server return the current state for
+                          each room returned.
+                      groupings:
+                        type: object
+                        title: Groupings
+                        description: |-
+                          Requests that the server partitions the result set
+                          based on the provided list of keys.
+                        properties:
+                          group_by:
+                            type: array
+                            title: Groups
+                            description: List of groups to request.
+                            items:
+                              type: object
+                              title: Group
+                              description: Configuration for group.
+                              properties:
+                                key:
+                                  type: string
+                                  title: Group Key
+                                  description: |-
+                                    Key that defines the group.
+                                  enum: ["room_id", "sender"]
+                    required: ["search_term"]
+            required: ["search_categories"]
+      responses:
+        200:
+          description: Results of the search.
+          schema:
+            type: object
+            title: Results
+            required: ["search_categories"]
+            properties:
+              search_categories:
+                type: object
+                title: Categories
+                description: Describes which categories to search in and
+                  their criteria.
+                properties:
+                  room_events:
+                    type: object
+                    title: Room Event Results
+                    description: Mapping of category name to search criteria.
+                    properties:
+                      count:
+                        type: number
+                        description: An approximate count of the total number of results found.
+                      results:
+                        type: array
+                        title: Results
+                        description: List of results in the requested order.
+                        items:
+                          type: object
+                          title: Result
+                          description: The result object.
+                          properties:
+                            rank:
+                              type: number
+                              description: A number that describes how closely
+                                this result matches the search. Higher is
+                                closer.
+                            result:
+                              type: object
+                              title: Event
+                              description: The event that matched.
+                              "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+                            context:
+                              type: object
+                              title: Event Context
+                              description: Context for result, if requested.
+                              properties:
+                                start:
+                                  type: string
+                                  title: Start Token
+                                  description: |-
+                                    Pagination token for the start of the chunk
+                                end:
+                                  type: string
+                                  title: End Token
+                                  description: |-
+                                    Pagination token for the end of the chunk
+                                profile_info:
+                                  type: object
+                                  title: Profile Information
+                                  description: |-
+                                    The historic profile information of the
+                                    users that sent the events returned.
+                                  additionalProperties:
+                                    type: object
+                                    title: User Profile
+                                    properties:
+                                      displayname:
+                                        type: string
+                                        title: Display name
+                                      avatar_url:
+                                        type: string
+                                        title: Avatar Url
+                                events_before:
+                                  type: array
+                                  title: Events Before
+                                  description: Events just before the result.
+                                  items:
+                                    title: Event
+                                    type: object
+                                    "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+                                events_after:
+                                  type: array
+                                  title: Events After
+                                  description: Events just after the result.
+                                  items:
+                                    title: Event
+                                    type: object
+                                    "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+                      state:
+                        type: object
+                        title: Current state
+                        description: |-
+                          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``.
+                        additionalProperties:
+                          type: array
+                          title: Room State
+                          items:
+                            "$ref": "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
+                      groups:
+                        type: object
+                        title: Groups
+                        description: Any groups that were requested.
+                        additionalProperties:
+                          type: object
+                          title: Group Key
+                          description: The results for a given group.
+                          additionalProperties:
+                            type: object
+                            title: Group Value
+                            description: |-
+                                The results for a particular group value.
+                            properties:
+                              next_batch:
+                                type: string
+                                title: Next Batch in Group
+                                description: |-
+                                  Token that can be used to get the next batch
+                                  of results in the group, by passing as the
+                                  `next_batch` parameter to the next call. If
+                                  this field is absent, there are no more
+                                  results in this group.
+                              order:
+                                type: integer
+                                title: Group Order
+                                description: |-
+                                  Key that can be used to order different
+                                  groups.
+                              results:
+                                type: array
+                                description: |-
+                                  Which results are in this group.
+                                items:
+                                  type: string
+                                  title: Result Event ID
+                      next_batch:
+                        type: string
+                        title: Next Batch
+                        description: |-
+                          Token that can be used to get the next batch of
+                          results, by passing as the `next_batch` parameter to
+                          the next call. If this field is absent, there are no
+                          more results.
+          examples:
+            application/json: |-
+               {
+                  "search_categories": {
+                    "room_events": {
+                      "groups": {
+                        "room_id": {
+                          "!qPewotXpIctQySfjSy:localhost": {
+                            "order": 1,
+                            "next_batch": "BdgFsdfHSf-dsFD",
+                            "results": [
+                              "$144429830826TWwbB:localhost"
+                            ]
+                          }
+                        }
+                      },
+                      "next_batch": "5FdgFsd234dfgsdfFD",
+                      "count": 1224,
+                      "results": [
+                        {
+                          "rank": 0.00424866,
+                          "result": {
+                            "age": 526228296,
+                            "content": {
+                              "body": "Test content martians and men",
+                              "msgtype": "m.text"
+                            },
+                            "event_id": "$144429830826TWwbB:localhost",
+                            "origin_server_ts": 1444298308034,
+                            "room_id": "!qPewotXpIctQySfjSy:localhost",
+                            "type": "m.room.message",
+                            "sender": "@test:localhost"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+        400:
+          description: Part of the request was invalid.
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Search

api/client-server/sync.yaml

@@ -1,28 +1,37 @@
+# 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 Client-Server v2 sync API"
+  title: "Matrix Client-Server sync API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
-basePath: /_matrix/client/v2_alpha
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/sync":
     get:
       summary: Synchronise the client's state and receive new messages.
       description: |-
         Synchronise the client's state with the latest state on the server.
-        Client's use this API when they first log in to get an initial snapshot
+        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.
       security:
@@ -32,7 +41,13 @@ paths:
           name: filter
           type: string
           description: |-
-            The ID of a filter created using the filter API.
+            The ID of a filter created using the filter API or a filter JSON
+            object encoded as a string. The server will detect whether it is
+            an ID or a JSON object by whether the first character is a ``"{"``
+            open brace. Passing the JSON inline is best suited to one off
+            requests. Creating a filter using the filter API is recommended for
+            clients that reuse the same filter multiple times, for example in
+            long poll requests.
           x-example: "66696p746572"
         - in: query
           name: since
@@ -40,6 +55,24 @@ paths:
           description: |-
             A point in time to continue a sync from.
           x-example: "s72594_4483_1934"
+        - in: query
+          name: full_state
+          type: boolean
+          description: |-
+            Controls whether to include the full state for all rooms the user
+            is a member of.
+
+            If this is set to ``true``, then all state events will be returned,
+            even if ``since`` is non-empty. The timeline will still be limited
+            by the ``since`` parameter. In this case, the ``timeout`` parameter
+            will be ignored and the query will return immediately, possibly with
+            an empty timeline.
+
+            If ``false``, and ``since`` is non-empty, only state which has
+            changed since the point indicated by ``since`` will be returned.
+
+            By default, this is ``false``.
+          x-example: "false"
         - in: query
           name: set_presence
           type: string
@@ -55,8 +88,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:
@@ -77,33 +114,26 @@ paths:
                 description: |-
                   Updates to rooms.
                 properties:
-                  joined:
-                    title: Joined
+                  join:
+                    title: Joined Rooms
                     type: object
+                    description: |-
+                      The rooms that the user has joined.
                     additionalProperties:
                       title: Joined Room
                       type: object
                       properties:
-                        event_map:
-                          title: EventMap
-                          type: object
-                          description: |-
-                            A map from event ID to events for this room. The
-                            events are referenced from the ``timeline`` and
-                            ``state`` keys for this room.
-                          additionalProperties:
-                            title: Event
-                            description: An event object.
-                            type: object
-                            allOf:
-                              - $ref: "core-event-schema/event.json"
                         state:
                           title: State
                           type: object
                           description: |-
-                            The state updates for the room.
+                            Updates to the state, between the time indicated by
+                            the ``since`` parameter, and the start of the
+                            ``timeline`` (or all state up to the start of the
+                            ``timeline``, if ``since`` is not given, or
+                            ``full_state`` is true).
                           allOf:
-                            - $ref: "definitions/room_event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -111,7 +141,7 @@ paths:
                             The timeline of messages and state changes in the
                             room.
                           allOf:
-                            - $ref: "definitions/timeline_batch.json"
+                            - $ref: "definitions/timeline_batch.yaml"
                         ephemeral:
                           title: Ephemeral
                           type: object
@@ -120,9 +150,33 @@ paths:
                             recorded in the timeline or state of the room.
                             e.g. typing.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
-                  invited:
-                    title: Invited
+                            - $ref: "definitions/event_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"
+                        "unread_notifications":
+                          title: Unread Notification Counts
+                          type: object
+                          description: |-
+                            Counts of unread notifications for this room
+                          properties:
+                            highlight_count:
+                                title: Highlighted notification count
+                                type: integer
+                                description: The number of unread notifications
+                                             for this room with the highlight flag set
+                            notification_count:
+                                title: Total notification count
+                                type: integer
+                                description: The total number of unread notifications
+                                             for this room
+                  invite:
+                    title: Invited Rooms
                     type: object
                     description: |-
                       The rooms that the user has been invited to.
@@ -135,7 +189,7 @@ paths:
                           type: object
                           description: |-
                             The state of a room that the user has been invited
-                            to. These state events may only have the `sender``,
+                            to. These state events may only have the ``sender``,
                             ``type``, ``state_key`` and ``content`` keys
                             present. These events do not replace any state that
                             the client already has for the room, for example if
@@ -147,38 +201,23 @@ paths:
                             delta against the archived ``state`` not the
                             ``invite_state``.
                           allOf:
-                            - $ref: "definitions/event_batch.json"
-                  archived:
-                    title: Archived
+                            - $ref: "definitions/event_batch.yaml"
+                  leave:
+                    title: Left rooms
                     type: object
                     description: |-
-                      The rooms that the user has left or been banned from. The
-                      entries in the room_map will lack an ``ephemeral`` key.
+                      The rooms that the user has left or been banned from.
                     additionalProperties:
-                      title: Archived Room
+                      title: Left Room
                       type: object
                       properties:
-                        event_map:
-                          title: EventMap
-                          type: object
-                          description: |-
-                            A map from event ID to events for this room. The
-                            events are referenced from the ``timeline`` and
-                            ``state`` keys for this room.
-                          additionalProperties:
-                            title: Event
-                            description: An event object.
-                            type: object
-                            allOf:
-                              - $ref: "core-event-schema/event.json"
                         state:
                           title: State
                           type: object
                           description: |-
-                            The state updates for the room up to the point when
-                            the user left.
+                            The state updates for the room up to the start of the timeline.
                           allOf:
-                            - $ref: "definitions/room_event_batch.json"
+                            - $ref: "definitions/event_batch.yaml"
                         timeline:
                           title: Timeline
                           type: object
@@ -186,14 +225,33 @@ paths:
                             The timeline of messages and state changes in the
                             room up to the point when the user left.
                           allOf:
-                            - $ref: "definitions/timeline_batch.json"
+                            - $ref: "definitions/timeline_batch.yaml"
               presence:
                 title: Presence
                 type: object
                 description: |-
                   The updates to the presence status of other users.
                 allOf:
-                  - $ref: "definitions/event_batch.json"
+                  - $ref: "definitions/event_batch.yaml"
+              account_data:
+                title: Account Data
+                type: object
+                description: |-
+                  The global private data created by this user.
+                allOf:
+                  - $ref: "definitions/event_batch.yaml"
+              to_device:
+                title: ToDevice
+                type: object
+                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|_.
           examples:
             application/json: |-
               {
@@ -207,45 +265,54 @@ paths:
                     }
                   ]
                 },
+                "account_data": {
+                  "events": [
+                    {
+                      "type": "org.example.custom.config",
+                      "content": {
+                        "custom_config_key": "custom_config_value"
+                      }
+                    }
+                  ]
+                },
                 "rooms": {
-                  "joined": {
+                  "join": {
                     "!726s6s6q:example.com": {
-                      "event_map": {
-                        "$66697273743031:example.com": {
-                          "sender": "@alice:example.com",
-                          "type": "m.room.member",
-                          "state_key": "@alice:example.com",
-                          "content": {"membership": "join"},
-                          "origin_server_ts": 1417731086795
-                        },
-                        "$7365636s6r6432:example.com": {
-                          "sender": "@bob:example.com",
-                          "type": "m.room.member",
-                          "state_key": "@bob:example.com",
-                          "content": {"membership": "join"},
-                          "origin_server_ts": 1417731086795
-                        },
-                        "$74686972643033:example.com": {
-                          "sender": "@alice:example.com",
-                          "type": "m.room.message",
-                          "unsigned": {"age": "124524", "txn_id": "1234"},
-                          "content": {
-                            "body": "I am a fish",
-                            "msgtype": "m.text"
-                          },
-                          "origin_server_ts": 1417731086797
-                        }
-                      },
                       "state": {
                         "events": [
-                          "$66697273743031:example.com",
-                          "$7365636s6r6432:example.com"
+                          {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.member",
+                            "state_key": "@alice:example.com",
+                            "content": {"membership": "join"},
+                            "origin_server_ts": 1417731086795,
+                            "event_id": "$66697273743031:example.com"
+                          }
                         ]
                       },
                       "timeline": {
                         "events": [
-                          "$7365636s6r6432:example.com",
-                          "$74686972643033:example.com"
+                          {
+                            "sender": "@bob:example.com",
+                            "type": "m.room.member",
+                            "state_key": "@bob:example.com",
+                            "content": {"membership": "join"},
+                            "prev_content": {"membership": "invite"},
+                            "origin_server_ts": 1417731086795,
+                            "event_id": "$7365636s6r6432:example.com"
+                          },
+                          {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.message",
+                            "age": 124524,
+                            "txn_id": "1234",
+                            "content": {
+                              "body": "I am a fish",
+                              "msgtype": "m.text"
+                            },
+                            "origin_server_ts": 1417731086797,
+                            "event_id": "$74686972643033:example.com"
+                          }
                         ],
                         "limited": true,
                         "prev_batch": "t34-23535_0_0"
@@ -253,15 +320,28 @@ paths:
                       "ephemeral": {
                         "events": [
                           {
-                            "room_id": "!726s6s6q:example.com",
                             "type": "m.typing",
                             "content": {"user_ids": ["@alice:example.com"]}
                           }
                         ]
+                      },
+                      "account_data": {
+                        "events": [
+                          {
+                            "type": "m.tag",
+                            "content": {"tags": {"work": {"order": 1}}}
+                          },
+                          {
+                            "type": "org.example.custom.room.config",
+                            "content": {
+                              "custom_config_key": "custom_config_value"
+                            }
+                          }
+                        ]
                       }
                     }
                   },
-                  "invited": {
+                  "invite": {
                     "!696r7674:example.com": {
                       "invite_state": {
                         "events": [
@@ -281,6 +361,8 @@ paths:
                       }
                     }
                   },
-                  "archived": {}
+                  "leave": {}
                 }
               }
+      tags:
+        - Room participation

api/client-server/tags.yaml

@@ -0,0 +1,162 @@
+# 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 Client-Server tag 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}/rooms/{roomId}/tags":
+    get:
+      summary: List the tags for a room.
+      description: |-
+        List the tags set by a user on a room.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to get tags for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: |-
+            The id of the room to get tags for.
+          x-example: "!726s6s6q:example.com"
+      responses:
+        200:
+          description:
+            The list of tags for the user for the room.
+          schema:
+            type: object
+            properties:
+              tags:
+                title: Tags
+                type: object
+          examples:
+            application/json: |-
+              {
+                "tags": {
+                  "work": {"order": "1"},
+                  "pinned": {}
+                }
+              }
+      tags:
+        - User data
+  "/user/{userId}/rooms/{roomId}/tags/{tag}":
+    put:
+      summary: Add a tag to a room.
+      description: |-
+        Add a tag to the room.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to add a tag for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: |-
+            The id of the room to add a tag to.
+          x-example: "!726s6s6q:example.com"
+        - in: path
+          type: string
+          name: tag
+          required: true
+          description: |-
+            The tag to add.
+          x-example: "work"
+        - in: body
+          name: body
+          required: true
+          description: |-
+            Extra data for the tag, e.g. ordering.
+          schema:
+            type: object
+            example: |-
+              {"order": "1"}
+      responses:
+        200:
+          description:
+            The tag was successfully added.
+          schema:
+            type: object
+          examples:
+            application/json: |-
+              {}
+      tags:
+        - User data
+    delete:
+      summary: Remove a tag from the room.
+      description: |-
+        Remove a tag from the room.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The id of the user to remove a tag for. The access token must be
+            authorized to make requests for this user id.
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: |-
+            The id of the room to remove a tag from.
+          x-example: "!726s6s6q:example.com"
+        - in: path
+          type: string
+          name: tag
+          required: true
+          description: |-
+            The tag to remove.
+          x-example: "work"
+      responses:
+        200:
+          description:
+            The tag was successfully removed
+          schema:
+            type: object
+          examples:
+            application/json: |-
+              {}
+      tags:
+        - User data

api/client-server/third_party_membership.yaml

@@ -0,0 +1,134 @@
+# 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 Client-Server Room Membership API for third party identifiers"
+  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}/invite":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        .. _invite-by-third-party-id-endpoint:
+
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API does not require that the inviter know the Matrix
+        identifier of the invitee, and instead relies on third party identifiers.
+        The homeserver uses an identity server to perform the mapping from
+        third party identifier to a Matrix identifier. The other is documented in the*
+        `joining rooms section`_.
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the identity server did know the Matrix user identifier for the
+        third party identifier, the homeserver will append a ``m.room.member``
+        event to the room.
+
+        If the identity server does not know a Matrix user identifier for the
+        passed third party identifier, the homeserver will issue an invitation
+        which can be accepted upon providing proof of ownership of the third
+        party identifier. This is achieved by the identity server generating a
+        token, which it gives to the inviting homeserver. The homeserver will
+        add an ``m.room.third_party_invite`` event into the graph for the room,
+        containing that token.
+
+        When the invitee binds the invited third party identifier to a Matrix
+        user ID, the identity server will give the user a list of pending
+        invitations, each containing:
+
+        - The room ID to which they were invited
+
+        - The token given to the homeserver
+
+        - A signature of the token, signed with the identity server's private key
+
+        - The matrix user ID who invited them to the room
+
+        If a token is requested from the identity server, the homeserver will
+        append a ``m.room.third_party_invite`` event to the room.
+
+        .. _joining rooms section: `invite-by-user-id-endpoint`_
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "id_server": "matrix.org",
+                "medium": "email",
+                "address": "cheeky@monkey.com"
+              }
+            properties:
+              id_server:
+                type: string
+                description: The hostname+port of the identity server which should be used for third party identifier lookups.
+              medium:
+                type: string
+                # TODO: Link to identity service spec when it eixsts
+                description: The kind of address being passed in the address field, for example ``email``.
+              address:
+                type: string
+                description: The invitee's third party identifier.
+            required: ["id_server", "medium", "address"]
+      responses:
+        200:
+          description: The user has been invited to join the room.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - 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"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/to_device.yaml

@@ -0,0 +1,89 @@
+# 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 Client-Server Send-to-device 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:
+  "/sendToDevice/{eventType}/{txnId}":
+    put:
+      summary: Send an event to a given set of devices.
+      description: |-
+        This endpoint is used to send send-to-device events to a set of
+        client devices.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.new_device"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate an
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            title: body
+            properties:
+              messages:
+                type: object
+                description: |-
+                  The messages to send. A map from user ID, to a map from
+                  device ID to message body. The device ID may also be `*`,
+                  meaning all known devices for the user.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    title: EventContent
+                    description: Message content
+                example: {
+                    "@alice:example.com": {
+                      "TLLBEANAAG": {
+                        "example_content_key": "value"
+                      }
+                    }
+                  }
+      responses:
+        200:
+          description:
+            The message was successfully sent.
+          examples:
+            application/json: |-
+              {}
+      tags:
+        - Send-to-Device messaging

api/client-server/typing.yaml

@@ -1,22 +1,31 @@
+# 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 Client-Server v1 Typing API"
+  title: "Matrix Client-Server Typing API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomId}/typing/{userId}":
     put:
@@ -74,4 +83,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - Room participation

api/client-server/v1/core-event-schema

@@ -1 +0,0 @@
-v1-event-schema/core-event-schema

api/client-server/v1/definitions/error.yaml

@@ -1,10 +0,0 @@
-type: object
-description: A Matrix-level Error
-properties:
-  errcode:
-    type: string
-    description: An error code.
-  error:
-    type: string
-    description: A human-readable error message.
-required: ["errcode"]

api/client-server/v1/definitions/push_condition.json

@@ -1,9 +0,0 @@
-{
-  "type": "object", 
-  "properties": {
-    "kind": {
-      "type": "string",
-      "enum": ["event_match", "profile_tag", "contains_display_name", "room_member_count"]
-    }
-  }
-}

api/client-server/v1/definitions/push_rule.json

@@ -1,20 +0,0 @@
-{
-  "type": "object", 
-  "properties": {
-    "default": {
-      "type": "boolean"
-    }, 
-    "enabled": {
-      "type": "boolean"
-    }, 
-    "rule_id": {
-      "type": "string"
-    }, 
-    "actions": {
-      "items": {
-        "type": ["object", "string"]
-      }, 
-      "type": "array"
-    }
-  }
-}

api/client-server/v1/definitions/push_ruleset.json

@@ -1,60 +0,0 @@
-{
-  "type": "object", 
-  "properties": {
-    "content": {
-      "items": {
-        "type": "object", 
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      }, 
-      "type": "array"
-    }, 
-    "override": {
-      "items": {
-        "type": "object", 
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      }, 
-      "type": "array"
-    }, 
-    "sender": {
-      "items": {
-        "type": "object", 
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      }, 
-      "type": "array"
-    }, 
-    "underride": {
-      "items": {
-        "type": "object", 
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      }, 
-      "type": "array"
-    }, 
-    "room": {
-      "items": {
-        "type": "object", 
-        "allOf": [
-          {
-            "$ref": "push_rule.json"
-          }
-        ]
-      }, 
-      "type": "array"
-    }
-  }
-}

api/client-server/v1/directory.yaml

@@ -1,87 +0,0 @@
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server v1 Directory API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/api/v1/directory
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
-paths:
-  "/room/{roomAlias}":
-    put:
-      summary: Create a new mapping from room alias to room ID.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomAlias
-          description: The room alias to set.
-          required: true
-        - in: body
-          name: roomInfo
-          description: Information about this room alias.
-          required: true
-          schema:
-            type: object
-            properties:
-              room_id:
-                type: string
-                description: The room ID to set.
-      responses:
-        200:
-          description: The mapping was created.
-          schema:
-            type: object  # empty json object
-    get:
-      summary: Get the room ID corresponding to this room alias.
-      parameters:
-        - in: path
-          type: string
-          name: roomAlias
-          description: The room alias.
-          required: true
-      responses:
-        200:
-          description: The room ID and other information for this alias.
-          schema:
-            type: object
-            properties:
-              room_id:
-                type: string
-                description: The room ID for this room alias.
-              servers:
-                type: array
-                description: A list of servers that are aware of this room ID.
-                items:
-                  type: string
-                  description: A server which is aware of this room ID.
-        404:
-          description: There is no mapped room ID for this room alias.
-    delete:
-      summary: Remove a mapping of room alias to room ID.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomAlias
-          description: The room alias to remove.
-          required: true
-      responses:
-        200:
-          description: The mapping was removed.
-          schema:
-            type: object  # empty json object
-

api/client-server/v1/login.yaml

@@ -1,147 +0,0 @@
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server v1 Registration and Login API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/api/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
-paths:
-  "/login":
-    post:
-      summary: Authenticates the user.
-      description: |-
-        Authenticates the user by password, and issues an access token they can
-        use to authorize themself in subsequent requests.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            example: |-
-              {
-                "username": "cheeky_monkey",
-                "password": "ilovebananas"
-              }
-            properties:
-              username:
-                type: string
-                description: The fully qualified user ID or just local part of the user ID, to log in.
-              password:
-                type: string
-                description: The user's password.
-            required: ["username", "password"]
-      responses:
-        200:
-          description: The user has been authenticated.
-          examples:
-            application/json: |-
-              {
-                "user_id": "@cheeky_monkey:matrix.org",
-                "access_token": "abc123",
-                "home_server": "matrix.org"
-              }
-          schema:
-            type: object
-            properties:
-              user_id:
-                type: string
-                description: The fully-qualified Matrix ID that has been registered.
-              access_token:
-                type: string
-                description: |-
-                  An access token for the account.
-                  This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-                  There is no specific error message to indicate that a request has failed because
-                  an access token has expired; instead, if a client has reason to believe its
-                  access token is valid, and it receives an auth error, they should attempt to
-                  refresh for a new token on failure, and retry the request with the new token.
-              refresh_token:
-                type: string
-                # TODO: Work out how to linkify /tokenrefresh
-                description: |-
-                  (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the /tokenrefresh API endpoint.
-              home_server:
-                type: string
-                description: The hostname of the Home Server on which the account has been registered.
-        403:
-          description: |-
-            The login attempt failed. For example, the password may have been incorrect.
-          examples:
-            application/json: |-
-              {"errcode": "M_FORBIDDEN"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-  "/tokenrefresh":
-    post:
-      summary: Exchanges a refresh token for an access token.
-      description: |-
-        Exchanges a refresh token for a new access token.
-        This is intended to be used if the access token has expired.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            example: |-
-              {
-                "refresh_token": "a1b2c3"
-              }
-            properties:
-              refresh_token:
-                type: string
-                description: The refresh token which was issued by the server.
-            required: ["refresh_token"]
-      responses:
-        200:
-          description: |-
-            The refresh token was accepted, and a new access token has been issued.
-            The passed refresh token is no longer valid and cannot be used.
-            A new refresh token will have been returned unless some policy does
-            not allow the user to continue to renew their session.
-          examples:
-            application/json: |-
-              {
-                "access_token": "bearwithme123",
-                "refresh_token": "exchangewithme987"
-              }
-          schema:
-            type: object
-            properties:
-              access_token:
-                type: string
-                description: |-
-                  An access token for the account.
-                  This access token can then be used to authorize other requests.
-                  The access token may expire at some point, and if so, it SHOULD come with a ``refresh_token``.
-              refresh_token:
-                type: string
-                description: (optional) A ``refresh_token`` may be exchanged for a new ``access_token`` using the TODO Linkify /tokenrefresh API endpoint.
-        403:
-          description: |-
-            The exchange attempt failed. For example, the refresh token may have already been used.
-          examples:
-            application/json: |-
-              {"errcode": "M_FORBIDDEN"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"

api/client-server/v1/membership.yaml

@@ -1,234 +0,0 @@
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server v1 Room Membership API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/client/api/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
-paths:
-  "/rooms/{roomId}/join":
-    post:
-      summary: Start the requesting user participating in a particular room.
-      description: |-
-        This API starts a user participating in a particular room, if that user
-        is allowed to participate in that room. After this call, the client is
-        allowed to see all current state events in the room, and all subsequent
-        events associated with the room until the user leaves the room.
-
-        After a user has joined a room, the room will appear as an entry in the
-        response of the |initialSync| API.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room identifier or room alias to join.
-          required: true
-          x-example: "#monkeys:matrix.org"
-      responses:
-        200:
-          description: |-
-            The room has been joined.
-
-            The joined room ID must be returned in the ``room_id`` field.
-          examples:
-            application/json: |-
-              {"room_id": "!d41d8cd:matrix.org"}
-          schema:
-            type: object
-        403:
-          description: |-
-            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
-              - 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."}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      x-alias:
-        canonical-link: "post-matrix-client-api-v1-rooms-roomid-join"
-        aliases:
-          - /join/{roomId}
-
-  # With an extra " " to disambiguate from the 3pid invite endpoint
-  # The extra space makes it sort first for what I'm sure is a good reason.
-  "/rooms/{roomId}/invite ":
-    post:
-      summary: Invite a user to participate in a particular room.
-      description: |-
-        *Note that there are two forms of this API, which are documented separately.
-        This version of the API requires that the inviter knows the Matrix
-        identifier of the invitee.*
-
-        This API invites a user to participate in a particular room.
-        They do not start participating in the room until they actually join the
-        room.
-
-        Only users currently in a particular room can invite other users to
-        join that room.
-
-        If the user was invited to the room, the home server will append a
-        ``m.room.member`` event to the room.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room identifier (not alias) to which to invite the user.
-          required: true
-          x-example: "!d41d8cd:matrix.org"
-        - in: body
-          name: body
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "user_id": "@cheeky_monkey:matrix.org"
-              }
-            properties:
-              user_id:
-                type: string
-                description: The fully qualified user ID of the invitee.
-            required: ["user_id"]
-      responses:
-        200:
-          description: The user has been invited to join the room.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object
-        403:
-          description: |-
-            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
-              - The invitee has been banned from the room.
-              - The invitee is already a member of the room.
-              - 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"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-
-  "/rooms/{roomId}/invite":
-    post:
-      summary: Invite a user to participate in a particular room.
-      description: |-
-        *Note that there are two forms of this API, which are documented separately.
-        This version of the API does not require that the inviter know the Matrix
-        identifier of the invitee, and instead relies on third party identifiers.
-        The homeserver uses an identity server to perform the mapping from
-        third party identifier to a Matrix identifier.*
-
-        This API invites a user to participate in a particular room.
-        They do not start participating in the room until they actually join the
-        room.
-
-        Only users currently in a particular room can invite other users to
-        join that room.
-
-        If the identity server did know the Matrix user identifier for the
-        third party identifier, the home server will append a ``m.room.member``
-        event to the room.
-
-        If the identity server does not know a Matrix user identifier for the
-        passed third party identifier, the homeserver will issue an invitation
-        which can be accepted upon providing proof of ownership of the third
-        party identifier. This is achieved by the identity server generating a
-        token, which it gives to the inviting homeserver. The homeserver will
-        add an ``m.room.third_party_invite`` event into the graph for the room,
-        containing that token.
-
-        When the invitee binds the invited third party identifier to a Matrix
-        user ID, the identity server will give the user a list of pending
-        invitations, each containing:
-
-          - The room ID to which they were invited
-
-          - The token given to the homeserver
-
-          - A signature of the token, signed with the identity server's private key
-
-          - The matrix user ID who invited them to the room
-
-        If a token is requested from the identity server, the home server will
-        append a ``m.room.third_party_invite`` event to the room.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room identifier (not alias) to which to invite the user.
-          required: true
-          x-example: "!d41d8cd:matrix.org"
-        - in: body
-          name: body
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "id_server": "matrix.org",
-                "medium": "email",
-                "address": "cheeky@monkey.com",
-                "display_name": "A very cheeky monkey"
-              }
-            properties:
-              id_server:
-                type: string
-                description: The hostname+port of the identity server which should be used for third party identifier lookups.
-              medium:
-                type: string
-                # TODO: Link to identity service spec when it eixsts
-                description: The kind of address being passed in the address field, for example ``email``.
-              address:
-                type: string
-                description: The invitee's third party identifier.
-              display_name:
-                type: string
-                description: A user-friendly string describing who has been invited. It should not contain the address of the invitee, to avoid leaking mappings between third party identities and matrix user IDs.
-            required: ["id_server", "medium", "address", "display_name"]
-      responses:
-        200:
-          description: The user has been invited to join the room.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object
-        403:
-          description: |-
-            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
-              - The invitee has been banned from the room.
-              - The invitee is already a member of the room.
-              - 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"}
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"

api/client-server/v1/push_notifier.yaml

@@ -1,192 +0,0 @@
-swagger: '2.0'
-info:
-  title: "Matrix Push Notification API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-  - http
-basePath: /_matrix/push/v1
-consumes:
-  - application/json
-produces:
-  - application/json
-paths:
-  "/notify":
-    post:
-      summary: Notify a push gateway about an event.
-      description: |-
-        This endpoint is invoked by HTTP pushers to notify a push gateway about
-        an event.
-        *NB: 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.*
-      parameters:
-        - in: body
-          name: notification
-          description: Information about the push notification.
-          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"
-                      }
-                  }
-                ]
-              }
-            required: ["notification", "counts", "devices"]
-            properties:
-              notification:
-                type: object
-                description: Information about the push notification
-                required: ["id", "room_id", "type", "sender"]
-                properties:
-                  id:
-                    type: string
-                    description: |-
-                      An identifier for this notification that may be used to
-                      detect duplicate notification requests. This is not
-                      necessarily the ID of the event that triggered the
-                      notification.
-                  room_id:
-                    type: string
-                    description: The ID of the room in which this event occurred.
-                  type:
-                    type: string
-                    description: The type of the event as in the event's ``type`` field.
-                  sender:
-                    type: string
-                    description: The sender of the event as in the corresponding event field.
-                  sender_display_name:
-                    type: string
-                    description: |-
-                      The current display name of the sender in the room in which
-                      the event occurred.
-                  room_name:
-                    type: string
-                    description: The name of the room in which the event occurred.
-                  room_alias:
-                    type: string
-                    description: An alias to display for the room in which the event occurred.
-                  user_is_target:
-                    type: boolean
-                    description: |-
-                      This is true if the user receiving the notification is the
-                      subject of a member event (i.e. the ``state_key`` of the
-                      member event is equal to the user's Matrix ID).
-                  prio:
-                    type: string
-                    enum: ["high", "low"]
-                    description: |-
-                      The priority of the notification. If omitted, ``high`` is
-                      assumed. This may be used by push gateways to deliver less
-                      time-sensitive notifications in a way that will preserve
-                      battery power on mobile devices.
-                  content:
-                    type: object
-                    title: EventContent
-                    description: |-
-                      The ``content`` field from the event, if present. If the
-                      event had no content field, this field is omitted.
-              counts:
-                type: object
-                description: |-
-                  This is a dictionary of the current number of unacknowledged
-                  communications for the recipient user. Counts whose value is
-                  zero are omitted.
-                properties:
-                  unread:
-                    type: integer
-                    description: |-
-                      The number of unread messages a user has across all of the
-                      rooms they are a member of.
-                  missed_calls:
-                    type: integer
-                    description: |-
-                      The number of unacknowledged missed calls a user has
-                      across all rooms of which they are a member.
-              devices:
-                type: array
-                title: Devices
-                description: |-
-                  This is an array of devices that the notification should be sent to.
-                items:
-                  type: object
-                  properties:
-                    app_id:
-                      type: string
-                      description: |-
-                        The app_id given when the pusher was created.
-                    pushkey:
-                      type: string
-                      description: The pushkey given when the pusher was created.
-                    pushkey_ts:
-                      type: integer
-                      description: |-
-                        The unix timestamp (in seconds) when the
-                        pushkey was last updated.
-                    data:
-                      type: object
-                      title: PusherData
-                      description: |-
-                        A dictionary of additional pusher-specific data. For
-                        'http' pushers, this is the data dictionary passed in at
-                        pusher creation minus the ``url`` key.
-                    tweaks:
-                      type: object
-                      title: Tweaks
-                      description: |-
-                        A dictionary of customisations made to the way this
-                        notification is to be presented. These are added by push rules.
-      responses:
-        200:
-          description: A list of rejected push keys.
-          examples:
-            application/json: |-
-              {
-                "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
-              }
-          schema:
-            type: object  # empty json object
-            properties:
-              rejected:
-                type: array
-                description: |-
-                  A list of all pushkeys given in the notification request that
-                  are not valid. These could have been rejected by an upstream
-                  gateway because they have expired or have never been valid.
-                  Homeservers must cease sending notification requests for these
-                  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.
-                items:
-                  type: string
-                  description: A pushkey
-

api/client-server/v1/v1-event-schema

@@ -1 +0,0 @@
-../../../event-schemas/schema/v1

api/client-server/v2_alpha/core-event-schema

@@ -1 +0,0 @@
-../../../event-schemas/schema/v1/core-event-schema

api/client-server/v2_alpha/definitions/definitions

@@ -1 +0,0 @@
-.

api/client-server/v2_alpha/definitions/error.yaml

@@ -1,10 +0,0 @@
-type: object
-description: A Matrix-level Error
-properties:
-  errcode:
-    type: string
-    description: An error code.
-  error:
-    type: string
-    description: A human-readable error message.
-required: ["errcode"]

api/client-server/v2_alpha/definitions/event_batch.json

@@ -1,12 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "events": {
-      "type": "array",
-      "description": "List of events",
-      "items": {
-        "type": "object"
-      }
-    }
-  }
-}

api/client-server/v2_alpha/definitions/event_filter.json

@@ -1,42 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "limit": {
-      "type": "integer",
-      "description":
-        "The maximum number of events to return."
-    },
-    "types": {
-      "type": "array",
-      "description":
-        "A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_types": {
-      "type": "array",
-      "description":
-        "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "senders": {
-      "type": "array",
-      "description":
-        "A list of senders IDs to include. If this list is absent then all senders are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_senders": {
-      "type": "array",
-      "description":
-        "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/v2_alpha/definitions/room_event_batch.json

@@ -1,12 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "events": {
-      "type": "array",
-      "description": "List of event ids",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/v2_alpha/definitions/room_event_filter.json

@@ -1,22 +0,0 @@
-{
-  "type": "object",
-  "allOf": [{"$ref": "definitions/event_filter.json"}],
-  "properties": {
-    "rooms": {
-      "type": "array",
-      "description":
-        "A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    },
-    "not_rooms": {
-      "type": "array",
-      "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. A '*' can be used as a wildcard to match any sequence of characters.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/v2_alpha/definitions/sync_filter.json

@@ -1,44 +0,0 @@
-{
-  "type": "object",
-  "properties": {
-    "room": {
-      "type": "object",
-      "properties": {
-        "state": {
-          "description":
-            "The state events to include for rooms.",
-          "allOf": [{"$ref": "definitions/room_event_filter.json"}]
-        },
-        "timeline": {
-          "description":
-            "The message and state update events to include for rooms.",
-          "allOf": [{"$ref": "definitions/room_event_filter.json"}]
-        },
-        "ephemeral": {
-          "description":
-            "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms.",
-          "allOf": [{"$ref": "definitions/room_event_filter.json"}]
-        }
-      }
-    },
-    "presence": {
-      "description":
-        "The presence updates to include.",
-      "allOf": [{"$ref": "definitions/event_filter.json"}]
-    },
-    "event_format": {
-      "description":
-        "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
-      "type": "string",
-      "enum": ["client", "federation"]
-    },
-    "event_fields": {
-      "type": "array",
-      "description":
-        "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\'. A server may include more fields than were requested.",
-      "items": {
-        "type": "string"
-      }
-    }
-  }
-}

api/client-server/v2_alpha/definitions/timeline_batch.json

@@ -1,14 +0,0 @@
-{
-  "type": "object",
-  "allOf": [{"$ref":"definitions/room_event_batch.json"}],
-  "properties": {
-    "limited": {
-      "type": "boolean",
-      "description": "Whether there are more events on the server"
-    },
-    "prev_batch": {
-      "type": "string",
-      "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve more events"
-    }
-  }
-}

api/client-server/versions.yaml

@@ -0,0 +1,54 @@
+# 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 Client-Server Versions API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client
+produces:
+  - application/json
+paths:
+  "/versions":
+    get:
+      summary: Gets the versions of the specification supported by the server.
+      description: |-
+        Gets the versions of the specification supported by the server.
+
+        Values will take the form ``rX.Y.Z``.
+
+        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``.
+      responses:
+        200:
+          description: The versions supported by the server.
+          examples:
+            application/json: |-
+              {
+                "versions": ["r0.0.1"]
+              }
+          schema:
+            type: object
+            properties:
+              versions:
+                type: array
+                description: The supported versions.
+                items:
+                  type: string
+                  description: The supported versions
+      tags:
+        - Server administration

api/client-server/voip.yaml

@@ -1,24 +1,33 @@
+# 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 Client-Server v1 Voice over IP API"
+  title: "Matrix Client-Server Voice over IP API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
   - https
   - http
-basePath: /_matrix/client/api/v1
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
 consumes:
   - application/json
 produces:
   - application/json
 securityDefinitions:
-  accessToken:
-    type: apiKey
-    description: The user_id or application service access_token
-    name: access_token
-    in: query
+  $ref: definitions/security.yaml
 paths:
-  "/turnServer":
+  "/voip/turnServer":
     get:
       summary: Obtain TURN server credentials.
       description: |-
@@ -65,4 +74,5 @@ paths:
           description: This request was rate-limited.
           schema:
             "$ref": "definitions/error.yaml"
-
+      tags:
+        - VOIP

api/files/css

@@ -3,7 +3,7 @@
   font-family: 'Droid Sans';
   font-style: normal;
   font-weight: 400;
-  src: local('Droid Sans'), local('DroidSans'), url(http://fonts.gstatic.com/s/droidsans/v5/s-BiyweUPV0v-yRb-cjciPk_vArhqVIZ0nv9q090hN8.woff2) format('woff2');
+  src: local('Droid Sans'), local('DroidSans'), url(http://fonts.gstatic.com/s/droidsans/v5/s-BiyweUPV0v-yRb-cjciPk_vArhqVIZ0nv9q090hN8.woff2), format('woff2');
   unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
 }
 /* latin */
@@ -11,6 +11,6 @@
   font-family: 'Droid Sans';
   font-style: normal;
   font-weight: 700;
-  src: local('Droid Sans Bold'), local('DroidSans-Bold'), url(http://fonts.gstatic.com/s/droidsans/v5/EFpQQyG9GqCrobXxL-KRMYWiMMZ7xLd792ULpGE4W_Y.woff2) format('woff2');
+  src: local('Droid Sans Bold'), local('DroidSans-Bold'), url(http://fonts.gstatic.com/s/droidsans/v5/EFpQQyG9GqCrobXxL-KRMYWiMMZ7xLd792ULpGE4W_Y.woff2), format('woff2');
   unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
 }

api/identity/lookup.yaml

@@ -0,0 +1,86 @@
+# 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 Identity Service Lookup  API"
+  version: "1.0.0"
+host: localhost:8090
+schemes:
+  - https
+  - http
+basePath: /_matrix/identity/api/v1
+produces:
+  - application/json
+paths:
+  "/lookup":
+    get:
+      summary: Look up the Matrix user ID for a 3pid.
+      description: Look up the Matrix user ID for a 3pid.
+      parameters:
+        - in: query
+          type: string
+          name: medium
+          required: true
+          description: The literal string "email".
+          x-example: "email"
+        - in: query
+          type: string
+          name: address
+          required: true
+          description: The email address being looked up.
+          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: |-
+              {
+                "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 literal string "email".
+              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 service which show that the association should be trusted, if you trust the verifying identity service.

api/identity/pubkey.yaml

@@ -0,0 +1,110 @@
+# 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 Identity Service Public Key API"
+  version: "1.0.0"
+host: localhost:8090
+schemes:
+  - https
+  - http
+basePath: /_matrix/identity/api/v1
+produces:
+  - application/json
+paths:
+  "/pubkey/{keyId}":
+    get:
+      summary: Get a public key.
+      description: |-
+        Get the public key for the passed key ID.
+      parameters:
+        - in: path
+          type: string
+          name: keyId
+          required: true
+          description: |-
+            The ID of the key. This should take the form algorithm:identifier
+            where algorithm identifies the signing algorithm, and the identifier
+            is an opaque string.
+          x-example: "ed25519:0"
+      responses:
+        200:
+          description:
+            The public key exists.
+          examples:
+            application/json: |-
+              {
+                "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+              }
+          schema:
+            type: object
+            properties:
+              public_key:
+                type: string
+  "/pubkey/isvalid":
+    get:
+      summary: Check whether a long-term public key is valid.
+      description: |-
+        Check whether a long-term public key is valid.
+      parameters:
+        - in: query
+          type: string
+          name: public_key
+          required: true
+          description: |-
+            The unpadded base64-encoded public key to check.
+          x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+      responses:
+        200:
+          description:
+            The validity of the public key.
+          examples:
+            application/json: |-
+              {
+                "valid": true
+              }
+          schema:
+            type: object
+            properties:
+              valid:
+                type: boolean
+                description: Whether the public key is recognised and is currently valid.
+  "/pubkey/ephemeral/isvalid":
+    get:
+      summary: Check whether a short-term public key is valid.
+      description: |-
+        Check whether a short-term public key is valid.
+      parameters:
+        - in: query
+          type: string
+          name: public_key
+          required: true
+          description: |-
+            The unpadded base64-encoded public key to check.
+          x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c"
+      responses:
+        200:
+          description:
+            The validity of the public key.
+          examples:
+            application/json: |-
+              {
+                "valid": true
+              }
+          schema:
+            type: object
+            properties:
+              valid:
+                type: boolean
+                description: Whether the public key is recognised and is currently valid.

api/push-gateway/push_notifier.yaml

@@ -0,0 +1,230 @@
+# 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 Push Notification API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/push/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/notify":
+    post:
+      summary: Notify a push gateway about an event.
+      description: |-
+        This endpoint is invoked by HTTP pushers to notify a push gateway about
+        an event or update the number of unread notifications a user has.
+        In the former case it will contain selected information about the event.
+        In either case it may contain numeric counts of the number of unread
+        events of different types the user has. The counts may be sent along
+        with a notification about an event or by themselves.
+
+        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
+        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.
+
+      parameters:
+        - in: body
+          name: notification
+          description: Information about the push notification.
+          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"
+                        }
+                    }
+                  ]
+                }
+              }
+            required: ["notification"]
+            properties:
+              notification:
+                type: object
+                title: Notification
+                description: Information about the push notification
+                required: ["devices"]
+                properties:
+                  event_id:
+                    type: string
+                    description: |-
+                      The Matrix event ID of the event being notified about.
+                      This is required if the notification is about a
+                      particular Matrix event. It may be omitted for notifications
+                      that only contain updated badge counts. This ID can and
+                      should be used to detect duplicate notification requests.
+                  room_id:
+                    type: string
+                    description: |-
+                      The ID of the room in which this event occurred.
+                      Required if the notification relates to a specific
+                      Matrix event.
+                  type:
+                    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: |-
+                      The current display name of the sender in the room in which
+                      the event occurred.
+                  room_name:
+                    type: string
+                    description: The name of the room in which the event occurred.
+                  room_alias:
+                    type: string
+                    description: An alias to display for the room in which the event occurred.
+                  user_is_target:
+                    type: boolean
+                    description: |-
+                      This is true if the user receiving the notification is the
+                      subject of a member event (i.e. the ``state_key`` of the
+                      member event is equal to the user's Matrix ID).
+                  prio:
+                    type: string
+                    enum: ["high", "low"]
+                    description: |-
+                      The priority of the notification. If omitted, ``high`` is
+                      assumed. This may be used by push gateways to deliver less
+                      time-sensitive notifications in a way that will preserve
+                      battery power on mobile devices.
+                  content:
+                    type: object
+                    title: EventContent
+                    description: |-
+                      The ``content`` field from the event, if present. If the
+                      event had no content field, this field is omitted.
+                  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.
+                    properties:
+                      unread:
+                        type: integer
+                        description: |-
+                          The number of unread messages a user has across all of the
+                          rooms they are a member of.
+                      missed_calls:
+                        type: integer
+                        description: |-
+                          The number of unacknowledged missed calls a user has
+                          across all rooms of which they are a member.
+                  devices:
+                    type: array
+                    title: Devices
+                    description: |-
+                      This is an array of devices that the notification should be sent to.
+                    items:
+                      type: object
+                      title: Device
+                      properties:
+                        app_id:
+                          type: string
+                          description: |-
+                            The app_id given when the pusher was created.
+                        pushkey:
+                          type: string
+                          description: The pushkey given when the pusher was created.
+                        pushkey_ts:
+                          type: integer
+                          description: |-
+                            The unix timestamp (in seconds) when the
+                            pushkey was last updated.
+                        data:
+                          type: object
+                          title: PusherData
+                          description: |-
+                            A dictionary of additional pusher-specific data. For
+                            'http' pushers, this is the data dictionary passed in at
+                            pusher creation minus the ``url`` key.
+                        tweaks:
+                          type: object
+                          title: Tweaks
+                          description: |-
+                            A dictionary of customisations made to the way this
+                            notification is to be presented. These are added by push rules.
+      responses:
+        200:
+          description: A list of rejected push keys.
+          examples:
+            application/json: |-
+              {
+                "rejected": [ "V2h5IG9uIGVhcnRoIGRpZCB5b3UgZGVjb2RlIHRoaXM/" ]
+              }
+          schema:
+            type: object  # empty json object
+            properties:
+              rejected:
+                type: array
+                description: |-
+                  A list of all pushkeys given in the notification request that
+                  are not valid. These could have been rejected by an upstream
+                  gateway because they have expired or have never been valid.
+                  Homeservers must cease sending notification requests for these
+                  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.
+                items:
+                  type: string
+                  description: A pushkey

api/swagger.html

@@ -1,76 +0,0 @@
-<!DOCTYPE html>
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-  <title>Matrix Client-Server API Documentation</title>
-  <link href="./files/css" rel="stylesheet" type="text/css">
-  <link href="./files/reset.css" media="screen" rel="stylesheet" type="text/css">
-  <link href="./files/screen.css" media="screen" rel="stylesheet" type="text/css">
-  <link href="./files/reset.css" media="print" rel="stylesheet" type="text/css">
-  <link href="./files/screen.css" media="print" rel="stylesheet" type="text/css">
-  <script type="text/javascript" src="./files/shred.bundle.js"></script>
-  <script src="./files/jquery-1.8.0.min.js" type="text/javascript"></script>
-  <script src="./files/jquery.slideto.min.js" type="text/javascript"></script>
-  <script src="./files/jquery.wiggle.min.js" type="text/javascript"></script>
-  <script src="./files/jquery.ba-bbq.min.js" type="text/javascript"></script>
-  <script src="./files/handlebars-1.0.0.js" type="text/javascript"></script>
-  <script src="./files/underscore-min.js" type="text/javascript"></script>
-  <script src="./files/backbone-min.js" type="text/javascript"></script>
-  <script src="./files/swagger.js" type="text/javascript"></script>
-  <script src="./files/swagger-ui.js" type="text/javascript"></script>
-  <script src="./files/highlight.7.3.pack.js" type="text/javascript"></script>
-
-  <!-- enabling this will enable oauth2 implicit scope support -->
-  <script src="./files/swagger-oauth.js" type="text/javascript"></script>
-
-  <script type="text/javascript">
-    $(function () {
-      window.swaggerUi = new SwaggerUi({
-      url: "http://localhost:8000/client-server/api-docs",
-      dom_id: "swagger-ui-container",
-      supportedSubmitMethods: ['get', 'post', 'put', 'delete'],
-      onComplete: function(swaggerApi, swaggerUi){
-        log("Loaded SwaggerUI");
-
-        if(typeof initOAuth == "function") {
-          initOAuth({
-            clientId: "your-client-id",
-            realm: "your-realms",
-            appName: "your-app-name"
-          });
-        }
-        $('pre code').each(function(i, e) {
-          hljs.highlightBlock(e)
-        });
-      },
-      onFailure: function(data) {
-        log("Unable to Load SwaggerUI");
-      },
-      docExpansion: "none"
-    });
-
-    $('#input_apiKey').change(function() {
-      var key = $('#input_apiKey')[0].value;
-      log("key: " + key);
-      if(key && key.trim() != "") {
-        log("added key " + key);
-        window.authorizations.add("key", new ApiKeyAuthorization("access_token", key, "query"));
-      }
-    })
-    window.swaggerUi.load();
-  });
-  </script>
-</head>
-
-<body class="swagger-section">
-<div id="swagger-header">
-  <div class="swagger-ui-wrap">
-    <form id="api_selector">
-      <div class="input"><input placeholder="access_token" id="input_apiKey" name="apiKey" type="text"></div>
-    </form>
-  </div>
-</div>
-
-<div id="message-bar" class="swagger-ui-wrap message-fail">Can't read from server.  It may not have the appropriate access-control-origin settings.</div>
-<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
-
-
-</body></html>