MSC4115: membership information on events (#4115)

* Proposal for membership information on events

* unstable prefix

* typo

* Update proposals/4115-membership-on-events.md

Co-authored-by: Matthew Hodgson <matthew@matrix.org>

* Update MSC4115

 * Make the new property *optional*.
 * Describe linear-DAG situation.
 * Mention client-side calculation as an alternative.

* spleling

* Return state *after* the event

This is much easier to calculate in Synapse.

* Clarificatoins to scope of MSC

* List of endpoints is incomplete

* RFC2119 keywords

* Remove non-issue potential issue

* Expand on why doing it client side doesn't work

* Update proposals/4115-membership-on-events.md

Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

* Update proposals/4115-membership-on-events.md

* Update proposals/4115-membership-on-events.md

* fix formatting

---------

Co-authored-by: Matthew Hodgson <matthew@matrix.org>
Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com>

.editorconfig

@@ -0,0 +1,7 @@
+# EditorConfig is awesome: https://EditorConfig.org
+root = true
+
+[*]
+insert_final_newline = true
+charset = utf-8
+max_line_length = 120

.github/PULL_REQUEST_TEMPLATE/ready-proposal.md

@@ -0,0 +1,22 @@
+---
+name: Proposal ready for review
+about: A proposal that is ready for review by the core team and community.
+title: ''
+labels: proposal, proposal-in-review
+assignees: ''
+
+---
+
+<!-- Put your "rendered" link here -->
+
+### Pull Request Checklist
+
+<!-- Please read CONTRIBUTING.md before submitting your pull request -->
+
+* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec-proposals/blob/master/CONTRIBUTING.md#sign-off)
+* [ ] Update the title and file name of your proposal to match this PR's number (after opening).
+* [ ] Pull request includes a ['Rendered' link](https://matrix.org/docs/spec/proposals#process) above.
+* [ ] Your MSC adheres to each point in the [MSC Checklist](MSC_CHECKLIST.md).
+* [ ] Ask in
+      [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) to
+      get feedback on this PR.

.github/PULL_REQUEST_TEMPLATE/wip-proposal.md

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

.github/_typos.toml

@@ -0,0 +1,11 @@
+[default]
+check-filename = true
+
+[default.extend-identifiers]
+OTK = "OTK"
+OTKs = "OTKs"
+
+[default.extend-words]
+OTK = "OTK"
+OTKs = "OTKs"
+Iy = "Iy"

.github/workflows/spell-check.yaml

@@ -0,0 +1,19 @@
+name: Spell Check
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  run:
+    name: Spell Check with Typos
+    runs-on: ubuntu-latest
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v4
+
+    - name: Check spelling of proposals
+      uses: crate-ci/typos@f2c1f08a7b3c1b96050cb786baaa2a94797bdb7d # v1.20.10
+      with:
+        config: ${{github.workspace}}/.github/_typos.toml

.gitignore

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

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to `matrix-spec-proposals`
+
+Thank you for taking the time to contribute to Matrix!
+
+This repository is for proposals for changes to the Matrix protocol. The process
+for submitting a proposal is described in
+[this repository's README](README.md#the-matrix-spec-process) or in further detail at
+https://spec.matrix.org/proposals/#process.
+
+## Sign off
+
+We ask that everybody who contributes to this project signs off their
+contributions, as explained below.
+
+We follow a simple 'inbound=outbound' model for contributions: the act of
+submitting an 'inbound' contribution means that the contributor agrees to
+license their contribution under the same terms as the project's overall
+'outbound' license - in our case, this is Apache Software License v2 (see
+[LICENSE](./LICENSE)).
+
+In order to have a concrete record that your contribution is intentional and
+you agree to license it under the same terms as the project's license, we've
+adopted the same lightweight approach used by the [Linux
+Kernel](https://www.kernel.org/doc/html/latest/process/submitting-patches.html),
+[Docker](https://github.com/docker/docker/blob/master/CONTRIBUTING.md), and
+many other projects: the [Developer Certificate of
+Origin](http://developercertificate.org/) (DCO). 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 :)
+
+### Private sign off
+
+If you would like to provide your legal name privately to the Matrix.org
+Foundation (instead of in a public commit or comment), you can do so by emailing
+your legal name and a link to the pull request to dco@matrix.org. It helps to
+include "sign off" or similar in the subject line. You will then be instructed
+further.
+
+Once private sign off is complete, doing so for future contributions will not be required.
+
+[1]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request

CONTRIBUTING.rst

@@ -1,153 +0,0 @@
-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 :)

MSC_CHECKLIST.md

@@ -0,0 +1,50 @@
+# MSC Checklist
+
+This document contains a list of final checks to perform on an MSC before it
+is accepted. The purpose is to prevent small clarifications needing to be
+made to the MSC after it has already been accepted.
+
+Spec Core Team (SCT) members, please ensure that all of the following checks
+pass before accepting a given Matrix Spec Change (MSC).
+
+MSC authors, feel free to ask in a thread on your PR or in the
+[#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) room for
+clarification of any of these points.
+
+- [ ] Are [appropriate
+      implementation(s)](https://spec.matrix.org/proposals/#implementing-a-proposal)
+      specified in the MSC’s PR description?
+- [ ] Are all MSCs that this MSC depends on already accepted?
+- [ ] For each new endpoint that is introduced:
+    - [ ] Have authentication requirements been specified?
+    - [ ] Have rate-limiting requirements been specified?
+    - [ ] Have guest access requirements been specified?
+    - [ ] Are error responses specified?
+        - [ ] Does each error case have a specified `errcode` (e.g. `M_FORBIDDEN`) and HTTP status code?
+            - [ ] If a new `errcode` is introduced, is it clear that it is new?
+- [ ] Will the MSC require a new room version, and if so, has that been made clear?
+    - [ ] Is the reason for a new room version clearly stated? For example,
+          modifying the set of redacted fields changes how event IDs are calculated,
+          thus requiring a new room version.
+- [ ] Are backwards-compatibility concerns appropriately addressed?
+- [ ] Are the [endpoint conventions](https://spec.matrix.org/latest/appendices/#conventions-for-matrix-apis) honoured?
+    - [ ] Do HTTP endpoints `use_underscores_like_this`?
+    - [ ] Will the endpoint return unbounded data? If so, has pagination been considered?
+    - [ ] If the endpoint utilises pagination, is it consistent with [the
+          appendices](https://spec.matrix.org/v1.8/appendices/#pagination)?
+- [ ] An introduction exists and clearly outlines the problem being solved.
+      Ideally, the first paragraph should be understandable by a non-technical
+      audience
+- [ ] All outstanding threads are resolved
+    - [ ] All feedback is incorporated into the proposal text itself, either as a fix or noted as an alternative
+- [ ] While the exact sections do not need to be present, the details implied by the proposal template are covered. Namely:
+    - [ ] Introduction
+    - [ ] Proposal text
+    - [ ] Potential issues
+    - [ ] Alternatives
+    - [ ] Security considerations
+    - [ ] Dependencies
+- [ ] Stable identifiers are used throughout the proposal, except for the unstable prefix section
+    - [ ] Unstable prefixes [consider](README.md#unstable-prefixes) the awkward accepted-but-not-merged state
+    - [ ] Chosen unstable prefixes do not pollute any global namespace (use “org.matrix.mscXXXX”, not “org.matrix”).
+- [ ] Changes have applicable [Sign Off](CONTRIBUTING.md#sign-off) from all authors/editors/contributors

README.md

@@ -0,0 +1,370 @@
+# Matrix Specification Proposals
+
+This repository contains proposals for changes to the [Matrix
+Protocol](http://spec.matrix.org), aka "Matrix Spec Changes" (MSCs). The
+[`proposals`](./proposals) directory contains MSCs which have been accepted.
+
+See below for instructions for creating new
+proposals. See also https://spec.matrix.org/proposals/ for more
+information on the MSC process, in particular
+https://spec.matrix.org/proposals/#process.
+
+The source of the Matrix specification itself is maintained at
+https://github.com/matrix-org/matrix-spec.
+
+## The Matrix Spec Process
+
+An MSC is meant to be a **technical document that unambiguously describes a
+change to the Matrix Spec**, while also justifying _why_ the change should be
+made.
+
+The document is used both to judge whether the change should be made as
+described *and* by developers to actually implement the changes. This is why
+it's important for an MSC to be fully fleshed out in technical detail, as once
+merged it's immediately part of the formal spec (even though it still needs to
+be transcribed into the actual spec itself).
+
+### What changes need to follow this process?
+
+In most cases a change to [the Matrix protocol](https://spec.matrix.org) will
+require an MSC. Changes that would not require an MSC are typically small and
+uncontentious, or are simply clarifications to the spec. Fixing typos in the
+spec do not require an MSC. In most cases, removing ambiguities do not either.
+The exception may be if implementations in the ecosystem have differing views
+on clarifying the ambiguity. In that case, an MSC is typically the best place
+to reach consensus.
+
+Ultimately, the [Spec Core Team](https://matrix.org/foundation) have the final
+say on this, but generally if the change would require updates to a
+non-insignificant portion of the Matrix implementation ecosystem or would be
+met with contention, an MSC is the best route to take. You can also ask in the
+[Matrix Spec](https://matrix.to/#/#matrix-spec:matrix.org) or [Office of the
+Spec Core Team](https://matrix.to/#/#sct-office:matrix.org) Matrix rooms for
+clarification.
+
+### Summary of the process
+
+The MSC process consists of three basic steps:
+
+1. **Write up the proposal** in a
+   [markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#GitHub-flavored-markdown)
+   document. (There's a [proposal
+   template](proposals/0000-proposal-template.md), but don't feel bound by it.)
+2. **Submit it as a Pull Request** to this repo, marking it as a draft until
+   it's ready for wider review.
+3. **Seek review** from the community. Once people are generally happy with it,
+   ask the [Spec Core Team](https://matrix.org/foundation) to look at it in
+   [the Office of the SCT Matrix
+   room](https://matrix.to/#/#sct-office:matrix.org). When the SCT are happy
+   with the proposal, and after a successful voting process, your pull request
+   is merged and the **MSC is now officially accepted** as part of the Matrix
+   Spec and can be used 🎉
+
+For simple changes this is really all you need to know. For larger or more
+controversial changes, getting an MSC merged can take more time and effort, but
+the overall process remains the same.
+
+Below is various guidance to try and help make the experience smoother.
+
+### Guidance on the process
+
+#### 1. Writing the proposal
+
+Come up with an idea. The idea can be for anything, but the solution (MSC)
+needs to benefit the Matrix ecosystem rather than yourself (or your company)
+specifically. Sometimes this means that the solution needs to be more generic
+than the specific itch that you are trying to scratch.
+
+Remember that an MSC is a formal technical document which will be used by
+others in the wider community to judge if the proposal should be accepted *and*
+to actually implement the changes in clients and servers. This means that for
+an MSC to be accepted it should include justifications and describe the
+technical changes unambiguously, including specifying what happens in any and
+all edge cases.
+
+There's a [proposal template](proposals/0000-proposal-template.md) under
+`docs/0000-proposal.md`, but you don't necessarily need to use it. Covering the
+same major points is fine.
+  * Note: At this stage, you won't have an MSC number, so feel free to use
+    `0000`, `XXXX`, or whatever other placeholder you feel comfortable with.
+
+Some tips for MSC writing:
+
+* Please wrap your lines to 120 characters maximum.
+  This allows readers to review your markdown without needing to horizontally
+  scroll back and forth. Many markdown text editors have this feature.
+* If you are referencing an existing endpoint in the spec, or another MSC, it
+  is very helpful to add a link to them so the reader does not need to search
+  themselves. Examples:
+    * "This MSC proposals an alternative to
+      [MSC3030](https://github.com/matrix-org/matrix-spec-proposals/pull/3030)."
+    * "A new field will be added to the response body of
+      [`/_matrix/client/v3/sync`](https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3sync)".
+        * Note: it is best to link to the latest stable version of the spec
+          (e.g. /v1.3, not /latest) - failing that,
+          [/unstable](https://spec.matrix.org/unstable/) if the change is not
+          yet in a released spec version.
+* GitHub supports rendering fancy diagrams from text with very little
+  effort using [Mermaid](https://mermaid-js.github.io/mermaid/#/). See [this
+  guide](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/)
+  for more information.
+* Take a look at the [MSC Checklist](MSC_CHECKLIST.md). When it comes time for
+  the Spec Core Team to review your MSC for acceptance, they'll use the items
+  on this checklist as a guide.
+
+#### 2. Submitting a Pull Request
+
+1. Open a [Pull
+   Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+   to add your proposal document to the [`proposals`](proposals) directory.
+   Note that this will require a GitHub account.
+      * [Mark your Pull Request as a
+        draft](https://github.blog/2019-02-14-introducing-draft-pull-requests/)
+        for now.
+2. The MSC number is the number of the pull request that is automatically
+   assigned by GitHub. Go back through and edit the document accordingly. Don't
+   forget the file name itself!
+3. Edit the pull request title to fit the format "MSC1234: Your proposal
+   title".
+4. Once your proposal is correctly formatted and ready for review from the
+   wider ecosystem, [take your Pull Request out of draft
+   status](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#marking-a-pull-request-as-ready-for-review).
+
+The Spec Core Team will notice this and apply various labels/status tracking to
+your MSC, which will announce it to the wider world.
+
+#### 3. Seeking review
+
+Seek review from the Matrix community. Generally this will happen naturally,
+but if you feel that your proposal is lacking review then ask for people's
+opinion in the [Matrix Spec room on
+Matrix](https://matrix.to/#/#matrix-spec:matrix.org).
+
+Reviews can take many forms, and do not need to be done solely by members of
+the Spec Core Team. Getting other people who are familiar with the area of
+Matrix you are proposing changes to is a great first step; especially those who
+may be implementing these changes in clients and/or homeservers.
+
+While the proposal is a work in progress, it's fine for it to be high level
+and hand-wavy in places, but remember that before it can be accepted it needs
+to be expanded to fully flesh out all the technical detail and edge cases.
+
+At this stage the proposal should also be implemented as a proof of concept
+somewhere to show that it _actually_ works in practice. This can be done on any
+client or server and doesn't need to be merged or released.
+
+#### 4. Entering Final Comment Period
+
+After the MSC has been implemented, fully fleshed out, and generally feels
+ready for final review, you should ask a member of the Spec Core Team to review it in
+the public [Spec Core Team Office room on
+Matrix](https://matrix.to/#/#sct-office:matrix.org). Someone from the SCT will
+then review it, and if all looks well will propose FCP
+to start.
+
+At this point, other members of the SCT will look at the proposal and consider
+it for inclusion in the spec.
+
+After enough SCT members have approved the proposal, the MSC will enter
+something called _Final Comment Period_. This is a 5 calendar day countdown to
+give anyone one last chance to raise any blockers or concerns about the
+proposed change. Typically MSCs pass this stage without incident, but it
+nevertheless serves as a safeguard.
+
+#### 5. The MSC is accepted
+
+Once FCP has ended and the MSC pull request is merged, the proposed change is
+considered officially part of the spec. Congratulations!
+
+Clients and servers can now start using the change, even though at this stage
+it still needs to be transcribed into the spec document. This happens over in
+https://github.com/matrix-org/matrix-spec/ and you are very welcome to do it
+yourself! Otherwise it will be handled by a Spec Core Team member. If you would
+like help with writing spec PRs, feel free to join and ask questions in the
+[Matrix Spec and Docs Authoring Room on Matrix](https://matrix.to/#/#matrix-docs:matrix.org).
+
+### Other useful information
+
+#### Unstable prefixes
+
+"Unstable prefixes" are the namespaces which are used by implementations while
+an MSC is not yet accepted.
+
+For instance, an MSC might propose that a `m.space`
+event type or an `/_matrix/client/v1/account/whoami` endpoint should exist.
+However, implementations cannot use these *stable* identifiers until the MSC
+has been accepted, as the underlying design may change at any time; the design is
+*unstable*.
+
+Instead, an MSC can define a namespace such as `org.matrix.msc1234` (using the real
+MSC number once known) which is added to the stable identifier, allowing for
+breaking changes between edits of the MSC itself, and preventing clashes with other
+MSCs that might attempt to add the same stable identifiers. 
+
+For the above examples, this would mean using `org.matrix.msc1234.space` and
+`/_matrix/client/unstable/org.matrix.msc1234/account/whoami`. It is also fine to
+use more traditional forms of namespace prefixes, such as `com.example.*` (e.g.
+`com.example.space`).
+
+Note: not all MSCs need to make use of unstable prefixes. They are only needed if
+implementations of your MSC need to exist in the wild before your MSC is accepted,
+*and* the MSC defines new endpoints, field names, etc.
+
+#### Unstable feature flags
+
+It is common when implementing support for an MSC that a client may wish to check
+if the homeserver it is communicating with supports an MSC.
+Typically, this is handled by the MSC defining an
+entry in the `unstable_features` dictionary of the
+[`/_matrix/client/versions`](https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientversions)
+endpoint, in the form of a new entry:
+
+```json5
+{
+  "unstable_features": {
+    "org.matrix.msc1234": true
+  }
+}
+```
+
+... with a value of `true` indicating that the feature is supported, and `false`
+or lack of the field altogether indicating the feature is not supported.
+
+#### When can I use stable identifiers?
+
+[According to the spec
+process](https://spec.matrix.org/proposals/#early-release-of-an-mscidea): once
+an MSC has been accepted, implementations are allowed to switch to *stable*
+identifiers. However, the MSC is still not yet part of a released spec version.
+
+In most cases, this is not an issue. For instance, if your MSC specifies a new
+event type, you can now start sending events with those types!
+
+Some MSCs introduce functionality where coordination between implementations is
+needed. For instance, a client may want to know whether a homeserver supports
+the stable version of a new endpoint before actually attempting to request it.
+Or perhaps the new event type you're trying to send relies on the homeserver
+recognising that new event type, and doing some work when it sees it.
+
+At this point, it may be best to wait until a new spec version is released with
+your changes. Homeservers that support the changes will eventually advertise
+that spec version under `/versions`, and your client can check for that.
+
+But if you really can't wait, then there is another option: the homeserver can
+tell clients that it supports *stable* indentifiers for your MSC before it
+enters a spec version, using yet another `unstable_features` flag:
+
+```json5
+{
+  "unstable_features": {
+    "org.matrix.msc1234": true,
+    "org.matrix.msc1234.stable": true
+  }
+}
+```
+
+If a client sees that `org.matrix.msc1234.stable` is `true`, it knows that it
+can start using stable identifiers for the new MSC, and the homeserver will
+accept and act on them accordingly.
+
+Note: While the general pattern of using the text ".stable" has emerged from
+previous MSCs, you can pick any name you like. You need only to clearly state
+their meaning, usually under an "Unstable prefixes" header in your MSC.
+
+See
+[MSC3827](https://github.com/matrix-org/matrix-spec-proposals/blob/main/proposals/3827-space-explore.md#unstable-prefix)
+for a good example of an MSC that wanted to use such a flag to speed up
+implementation rollout, and how it did so.
+
+#### Room versions
+
+To summarize [the spec](https://spec.matrix.org/latest/rooms/) on room
+versions: they are how servers agree upon algorithms in a decentralized world
+like ours. Examples of changes that require a new room version include anything that changes:
+ * The format of the core event structure (such as renaming a top-level field,
+   or modifying [the redaction
+   algorithm](https://spec.matrix.org/latest/client-server-api/#redactions)),
+   therefore altering the [reference
+   hash](https://spec.matrix.org/latest/server-server-api/#calculating-the-reference-hash-for-an-event)
+   of an event.
+ * [The authorisation of
+   events](https://spec.matrix.org/latest/server-server-api/#authorization-rules)
+   (such as changes to power levels).
+
+Unstable prefixes (see above) for room versions work the same as they do for
+other identifiers; your unstable room version may be called
+"org.matrix.msc1234".
+
+In order for the changes to end up in a "real" room version (the ones listed in
+the spec), it will need a second MSC which aggregates a bunch of functionality
+from various MSCs into a single room version. Typically these sorts of curating
+MSCs are written by the Spec Core Team given the complexity in wording, but
+you're more than welcome to bring an MSC forward which makes the version real.
+
+For an example of what introducing a new room version-required feature can look
+like, see [MSC3667](https://github.com/matrix-org/matrix-doc/pull/3667). For an
+example of what making a new "real" room version looks like, see
+[MSC3604](https://github.com/matrix-org/matrix-doc/pull/3604).
+
+#### Ownership of MSCs and closing them
+
+If an author decides that they would no longer like to pursue their MSC, they
+can either pass ownership of it off to someone else, or close it themselves.
+
+* The author of an MSC can close their MSC at any time before FCP by simply
+  closing the pull request.
+* To appoint another user as an author of the MSC (either to replace the author
+  entirely or to provide additional help), make a note in the MSC's PR
+  description by writing the following on its own line:
+
+  ```
+  Author: @username
+  ```
+
+  where `@username` is a valid GitHub username. Multiple such lines can be
+  added.
+
+  Finally, [give that user access to write to your fork of
+  matrix-spec-proposals on
+  GitHub](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository),
+  which your PR originates from. This will allow them to change the text of
+  your MSC.
+
+Similar to accepting an MSC, the Spec Core Team may propose a Final Comment
+Period with a disposition of "close". This can happen if the MSC appears
+abandoned by its author, or the idea is widely rejected by the community. A
+vote and final comment period will still be required for the motion to pass.
+
+Additionally, FCP can be also proposed with a disposition of "postpone". This
+may be done for MSCs for which the proposed changes do not make sense for the
+current state of the ecosystem, but may make sense further down the road.
+
+## Asking for help
+
+The Matrix community and members of the Spec Core Team are here to help guide
+you through the process!
+
+If you'd just like to get initial feedback about an idea that's not fully
+fleshed out yet, creating an issue at
+https://github.com/matrix-org/matrix-spec/issues is a great place to start. Be
+sure to search for any existing issues first to see if someone has already had
+the same idea!
+
+A few official rooms exist on Matrix where your questions can be answered, or
+feedback on your proposal can be requested:
+
+* [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org) -
+  General chat for MSCs, the spec, and pretty much anything in that sphere.
+* [#sct-office:matrix.org](https://matrix.to/#/#sct-office:matrix.org) - Where
+  the Spec Core Team hangs out and is available. This room is intended to have
+  extremely high signal and low noise, primarily to ensure that MSCs are not
+  falling through the cracks. If an MSC requires attention or comment from Spec
+  Core Team members, bring it up here.
+* [#matrix-spec-process:matrix.org](https://matrix.to/#/#matrix-spec-process:matrix.org) - A
+  room dedicated to [the spec process
+  itself](https://spec.matrix.org/proposals/#process). If you have any
+  questions about or suggestions to improve the Matrix Spec process, ask them
+  here.
+* [#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) - A
+  quieter room for discussion of the [formal spec
+  text](https://spec.matrix.org) and [matrix.org](https://matrix.org) website.

README.rst

@@ -1,39 +0,0 @@
-This repository contains the documentation for Matrix.
-
-Structure
-=========
-
-- ``api`` : Contains the HTTP API specification.
-- ``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
-  documents, e.g. documentation style, guidelines.
-- ``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
-  decisions, examples, use cases, etc.
-- ``templating``: Contains the templates and templating system used to
-  generate the spec.
-
-Contributing
-============
-
-Known issues with the specification are represented as JIRA issues at
-`<https://matrix.org/jira/browse/SPEC>`_.
-
-If you want to ask more about the specification, join us on
-`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
-
-If you would like to contribute to the specification or supporting
-documentation, see `<CONTRIBUTING.rst>`_.
-
-.. _JSON Schema: http://json-schema.org/

api/README

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

api/application-service/application_service.yaml

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

api/check_examples.py

@@ -1,142 +0,0 @@
-#! /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
-import os
-
-
-def import_error(module, package, debian, error):
-    sys.stderr.write((
-        "Error importing %(module)s: %(error)r\n"
-        "To install %(module)s run:\n"
-        "  pip install %(package)s\n"
-        "or on Debian run:\n"
-        "  sudo apt-get install python-%(debian)s\n"
-    ) % locals())
-    if __name__ == '__main__':
-        sys.exit(1)
-
-try:
-    import jsonschema
-except ImportError as e:
-    import_error("jsonschema", "jsonschema", "jsonschema", e)
-    raise
-
-try:
-    import yaml
-except ImportError as e:
-    import_error("yaml", "PyYAML", "yaml", e)
-    raise
-
-
-def check_parameter(filepath, request, parameter):
-    schema = parameter.get("schema")
-    example = None
-    try:
-        example_json = schema.get('example')
-        if example_json and not schema.get("format") == "byte":
-            example = json.loads(example_json)
-    except Exception as e:
-        raise ValueError("Error parsing JSON example request for %r" % (
-            request
-        ), e)
-    fileurl = "file://" + os.path.abspath(filepath)
-    if example and schema:
-        try:
-            print ("Checking request schema for: %r %r" % (
-                filepath, request
-            ))
-            # Setting the 'id' tells jsonschema where the file is so that it
-            # can correctly resolve relative $ref references in the schema
-            schema['id'] = fileurl
-            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
-            jsonschema.validate(example, schema, resolver=resolver)
-        except Exception as e:
-            raise ValueError("Error validating JSON schema for %r" % (
-                request
-            ), e)
-
-
-def check_response(filepath, request, code, response):
-    example = None
-    try:
-        example_json = response.get('examples', {}).get('application/json')
-        if example_json:
-            example = json.loads(example_json)
-    except Exception as e:
-        raise ValueError("Error parsing JSON example response for %r %r" % (
-            request, code
-        ), e)
-    schema = response.get('schema')
-    fileurl = "file://" + os.path.abspath(filepath)
-    if example and schema:
-        try:
-            print ("Checking response schema for: %r %r %r" % (
-                filepath, request, code
-            ))
-            # Setting the 'id' tells jsonschema where the file is so that it
-            # can correctly resolve relative $ref references in the schema
-            schema['id'] = fileurl
-            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
-            jsonschema.validate(example, schema, resolver=resolver)
-        except Exception as e:
-            raise ValueError("Error validating JSON schema for %r %r" % (
-                request, code
-            ), e)
-
-
-def check_swagger_file(filepath):
-    with open(filepath) as f:
-        swagger = yaml.load(f)
-
-    for path, path_api in swagger.get('paths', {}).items():
-
-        for method, request_api in path_api.items():
-            request = "%s %s" % (method.upper(), path)
-            for parameter in request_api.get('parameters', ()):
-                if parameter['in'] == 'body':
-                    check_parameter(filepath, request, parameter)
-
-            try:
-                responses = request_api['responses']
-            except KeyError:
-                raise ValueError("No responses for %r" % (request,))
-            for code, response in responses.items():
-                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:
-        paths = []
-        for (root, dirs, files) in os.walk(os.curdir):
-            for filename in files:
-                if filename.endswith(".yaml"):
-                    paths.append(os.path.join(root, filename))
-    for path in paths:
-        try:
-            check_swagger_file(path)
-        except Exception as e:
-            raise ValueError("Error checking file %r" % (path,), e)

api/client-server/account-data.yaml

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

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

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

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

@@ -1,144 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Content Repository API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
-produces:
-  - application/json
-  - "*/*"
-paths:
-  "/upload":
-    post:
-      summary: Upload some content to the content repository.
-      produces: ["application/json"]
-      parameters:
-        - in: header
-          name: Content-Type
-          type: string
-          description: The content type of the file being uploaded
-          x-example: "Content-Type: audio/mpeg"
-        - in: body
-          name: "<content>"
-          description: The content to be uploaded.
-          required: true
-          schema:
-            type: string
-            example: "<bytes>"
-            format: byte
-      responses:
-        200:
-          description: The MXC URI for the uploaded content.
-          schema:
-            type: object
-            required: ["content_uri"]
-            properties:
-              content_uri:
-                type: string
-                description: "The MXC URI to the uploaded content."
-          examples:
-            "application/json": |-
-              {
-                "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
-              }
-      tags:
-        - Media
-  "/download/{serverName}/{mediaId}":
-    get:
-      summary: "Download content from the content repository."
-      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)
-      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 the file that was previously uploaded, if set."
-              type: "string"
-          schema:
-            type: file
-      tags:
-        - Media
-  "/thumbnail/{serverName}/{mediaId}":
-    get:
-      summary: "Download a thumbnail of the content from the content repository."
-      produces: ["image/jpeg", "image/png"]
-      parameters:
-        - in: path
-          type: string
-          name: serverName
-          required: true
-          x-example: matrix.org
-          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: query
-          type: integer
-          x-example: 64
-          name: width
-          description: |-
-            The *desired* width of the thumbnail. The actual thumbnail may not
-            match the size specified.
-        - in: query
-          type: integer
-          x-example: 64
-          name: height
-          description: |-
-            The *desired* height of the thumbnail. The actual thumbnail may not
-            match the size specified.
-        - in: query
-          type: string
-          enum: ["crop", "scale"]
-          name: method
-          x-example: "scale"
-          description: The desired resizing method.
-      responses:
-        200:
-          description: "A thumbnail of the requested content."
-          headers:
-            Content-Type:
-              description: "The content type of the thumbnail."
-              type: "string"
-              enum: ["image/jpeg", "image/png"]
-          schema:
-            type: file
-      tags:
-        - Media

api/client-server/create_room.yaml

@@ -1,179 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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.
-      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 clober 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``.
-
-      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 body is malformed or the room alias specified is already taken.
-      tags:
-        - Room creation

api/client-server/definitions/auth_data.yaml

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

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

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

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

api/client-server/definitions/event.yaml

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

api/client-server/definitions/event_batch.yaml

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

api/client-server/definitions/event_filter.yaml

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

@@ -1,21 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-properties:
-  kind:
-    enum:
-    - event_match
-    - contains_display_name
-    - room_member_count
-    type: string
-type: object

api/client-server/definitions/push_rule.yaml

@@ -1,28 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-properties:
-  actions:
-    items:
-      type:
-      - object
-      - string
-    type: array
-  default:
-    type: boolean
-  enabled:
-    type: boolean
-  rule_id:
-    type: string
-title: PushRule
-type: object

api/client-server/definitions/push_ruleset.yaml

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

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

api/client-server/definitions/security.yaml

@@ -1,18 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-accessToken:
-  type: apiKey
-  description: The access_token returned by a call to ``/login`` or ``/tokenrefresh``
-  name: access_token
-  in: query

api/client-server/definitions/sync_filter.yaml

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

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

@@ -1,149 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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 ID.
-                items:
-                  type: string
-                  description: A server which is aware of this room ID.
-          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 ID !abnjk1jdasj98:capuchins.com 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

@@ -1,165 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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,152 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server filter API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $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 future requests to
-        restrict which events are returned to the client.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          required: true
-          description:
-            The id of the user uploading the filter. The access token must be
-            authorized to make requests for this user id.
-          x-example: "@alice:example.com"
-        - in: body
-          name: filter
-          required: true
-          description: The filter to upload.
-          schema:
-            type: object
-            allOf:
-              - $ref: "definitions/sync_filter.yaml"
-            example: |-
-              {
-                "room": {
-                  "state": {
-                    "types": ["m.room.*"],
-                    "not_rooms": ["!726s6s6q:example.com"]
-                  },
-                  "timeline": {
-                    "limit": 10,
-                    "types": ["m.room.message"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  },
-                  "ephemeral": {
-                    "types": ["m.receipt", "m.typing"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  }
-                },
-                "presence": {
-                  "types": ["m.presence"],
-                  "not_senders": ["@alice:example.com"]
-                },
-                "event_format": "client",
-                "event_fields": ["type", "content", "sender"]
-              }
-      responses:
-        200:
-          description: The filter was created.
-          examples:
-            application/json: |-
-              {
-                "filter_id": "66696p746572"
-              }
-          schema:
-            type: object
-            properties:
-              filter_id:
-                type: string
-                description: |-
-                  The ID of the filter that was created.
-      tags:
-        - Room participation
-  "/user/{userId}/filter/{filterId}":
-    get:
-      summary: Download a filter
-      parameters:
-        - in: path
-          name: userId
-          type: string
-          description: |-
-            The user ID to download a filter for.
-          x-example: "@alice:example.com"
-          required: true
-        - in: path
-          name: filterId
-          type: string
-          description: |-
-            The filter ID to download.
-          x-example: "66696p746572"
-          required: true
-      responses:
-        200:
-          description: |-
-            "The filter defintion"
-          examples:
-            application/json: |-
-              {
-                "room": {
-                  "state": {
-                    "types": ["m.room.*"],
-                    "not_rooms": ["!726s6s6q:example.com"]
-                  },
-                  "timeline": {
-                    "limit": 10,
-                    "types": ["m.room.message"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  },
-                  "ephemeral": {
-                    "types": ["m.receipt", "m.typing"],
-                    "not_rooms": ["!726s6s6q:example.com"],
-                    "not_senders": ["@spam:example.com"]
-                  }
-                },
-                "presence": {
-                  "types": ["m.presence"],
-                  "not_senders": ["@alice:example.com"]
-                },
-                "event_format": "client",
-                "event_fields": ["type", "content", "sender"]
-              }
-          schema:
-            type: object
-            allOf:
-              - $ref: "definitions/sync_filter.yaml"
-      tags:
-        - Room participation

api/client-server/inviting.yaml

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

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

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

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

@@ -1,116 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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.
-      responses:
-        200:
-          description: A list of the rooms on the server.
-          schema:
-            type: object
-            description: A list of the rooms on the server.
-            properties:
-              chunk:
-                title: "PublicRoomsChunks"
-                type: array
-                description: |-
-                  A paginated chunk of public rooms.
-                items:
-                  type: object
-                  title: "PublicRoomsChunk"
-                  properties:
-                    aliases:
-                      type: array
-                      description: |-
-                        Aliases of the room. May be empty.
-                      items:
-                        type: string
-                    name:
-                      type: string
-                      description: |-
-                        The name of the room, if any. May be null.
-                    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. May be null.
-                    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.
-              start:
-                type: string
-                description: |-
-                  A pagination token for the response.
-              end:
-                type: string
-                description: |-
-                  A pagination token for the response.
-          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
-                  }
-                ],
-                "start": "p190q",
-                "end": "p1902"
-              }
-        400:
-          description: >
-            The request body is malformed or the room alias specified is already taken.
-      tags:
-        - Room discovery

api/client-server/login.yaml

@@ -1,178 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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.
-      parameters:
-        - in: body
-          name: body
-          schema:
-            type: object
-            example: |-
-              {
-                "type": "m.login.password",
-                "user": "cheeky_monkey",
-                "password": "ilovebananas"
-              }
-            properties:
-              type:
-                type: string
-                description: The login type being used. Currently only "m.login.password" is supported.
-              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: The user's password.
-            required: ["type", "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 homeserver on which the account has been registered.
-        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
-  "/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"
-      tags:
-        - Session management

api/client-server/logout.yaml

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

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

@@ -1,433 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Sync 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 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. 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"
-      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."
-      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:
-        - in: query
-          type: integer
-          name: limit
-          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.
-          examples:
-            application/json: |-
-              {
-                  "end": "s3456_9_0",
-                  "presence": [
-                      {
-                          "content": {
-                              "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                              "displayname": "Bob",
-                              "last_active_ago": 31053,
-                              "presence": "online",
-                              "user_id": "@bob:localhost"
-                          },
-                          "type": "m.presence"
-                      }
-                  ],
-                  "account_data": [
-                    {
-                      "type": "org.example.custom.config",
-                      "content": {
-                        "custom_config_key": "custom_config_value"
-                      }
-                    }
-                  ],
-                  "rooms": [
-                      {
-                          "membership": "join",
-                          "messages": {
-                              "chunk": [
-                                  {
-                                      "age": 343513403,
-                                      "content": {
-                                          "body": "foo",
-                                          "msgtype": "m.text"
-                                      },
-                                      "event_id": "$14328044851tzTJS:localhost",
-                                      "origin_server_ts": 1432804485886,
-                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "type": "m.room.message",
-                                      "sender": "@alice:localhost"
-                                  },
-                                  {
-                                      "age": 343511809,
-                                      "content": {
-                                          "body": "bar",
-                                          "msgtype": "m.text"
-                                      },
-                                      "event_id": "$14328044872spjFg:localhost",
-                                      "origin_server_ts": 1432804487480,
-                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                      "type": "m.room.message",
-                                      "sender": "@bob:localhost"
-                                  }
-                              ],
-                              "end": "s3456_9_0",
-                              "start": "t44-3453_9_0"
-                          },
-                          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                          "state": [
-                              {
-                                  "age": 7148266897,
-                                  "content": {
-                                      "join_rule": "public"
-                                  },
-                                  "event_id": "$14259997323TLwtb:localhost",
-                                  "origin_server_ts": 1425999732392,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.join_rules",
-                                  "sender": "@alice:localhost"
-                              },
-                              {
-                                  "age": 6547561012,
-                                  "content": {
-                                      "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                                      "membership": "join"
-                                  },
-                                  "event_id": "$1426600438280zExKY:localhost",
-                                  "membership": "join",
-                                  "origin_server_ts": 1426600438277,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "@alice:localhost",
-                                  "type": "m.room.member",
-                                  "sender": "@alice:localhost"
-                              },
-                              {
-                                  "age": 7148267200,
-                                  "content": {
-                                      "creator": "@alice:localhost"
-                                  },
-                                  "event_id": "$14259997320KhbwJ:localhost",
-                                  "origin_server_ts": 1425999732089,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.create",
-                                  "sender": "@alice:localhost"
-                              },
-                              {
-                                  "age": 1622568720,
-                                  "content": {
-                                      "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                                      "displayname": "Bob",
-                                      "membership": "join"
-                                  },
-                                  "event_id": "$1431525430134MxlLX:localhost",
-                                  "origin_server_ts": 1431525430569,
-                                  "replaces_state": "$142652023736BSXcM:localhost",
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "@bob:localhost",
-                                  "type": "m.room.member",
-                                  "sender": "@bob:localhost"
-                              },
-                              {
-                                  "age": 7148267004,
-                                  "content": {
-                                      "ban": 50,
-                                      "events": {
-                                          "m.room.name": 100,
-                                          "m.room.power_levels": 100
-                                      },
-                                      "events_default": 0,
-                                      "kick": 50,
-                                      "redact": 50,
-                                      "state_default": 50,
-                                      "users": {
-                                          "@alice:localhost": 100
-                                      },
-                                      "users_default": 0
-                                  },
-                                  "event_id": "$14259997322mqfaq:localhost",
-                                  "origin_server_ts": 1425999732285,
-                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
-                                  "state_key": "",
-                                  "type": "m.room.power_levels",
-                                  "sender": "@alice:localhost"
-                              }
-                          ],
-                          "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"
-                              }
-                            }
-                          ]
-                      }
-                  ]
-              }
-          schema:
-            type: object
-            properties:
-              end:
-                type: string
-                description: |-
-                  A token which correlates to the last value in ``chunk``. This
-                  token should be used with the ``/events`` API to listen for new
-                  events.
-              presence:
-                type: array
-                description: A list of presence events.
-                items:
-                  type: object
-                  title: Event
-                  allOf:
-                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
-              rooms:
-                type: array
-                items:
-                  type: object
-                  title: RoomInfo
-                  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"]
-                    invite:
-                        type: object
-                        title: "InviteEvent"
-                        description: "The invite event if ``membership`` is ``invite``"
-                        allOf:
-                          - "$ref": "definitions/event-schemas/schema/m.room.member"
-                    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", "membership"]
-            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:
-        - in: path
-          type: string
-          name: eventId
-          description: The event ID to get.
-          required: true
-          x-example: "$asfDuShaf7Gafaw:matrix.org"
-      responses:
-        200:
-          description: The full event.
-          examples:
-            application/json: |-
-              {
-                "content": {
-                  "body": "Hello world!",
-                  "msgtype": "m.text"
-                },
-                "room_id": "!wfgy43Sg4a:matrix.org",
-                "sender": "@bob:matrix.org",
-                "event_id": "$asfDuShaf7Gafaw:matrix.org",
-                "type": "m.room.message"
-              }
-          schema:
-            allOf:
-              - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
-        404:
-          description: The event was not found or you do not have permission to read this event.
-      tags:
-        - Room participation
-      deprecated: true

api/client-server/peeking_events.yaml

@@ -1,114 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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,225 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Presence 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:
-  "/presence/{userId}/status":
-    put:
-      summary: Update this user's presence state.
-      description: |-
-        This API sets the given user's presence state. When setting the status,
-        the activity time is updated to reflect that activity; the client does
-        not need to specify the ``last_active_ago`` field. You cannot set the
-        presence state of another user.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence state to update.
-          required: true
-          x-example: "@alice:example.com"
-        - in: body
-          name: presenceState
-          description: The updated presence state.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "presence": "online",
-                "status_msg": "I am here."
-              }
-            properties:
-              presence:
-                type: string
-                enum: ["online", "offline", "unavailable"]
-                description: The new presence state.
-              status_msg:
-                type: string
-                description: "The status message to attach to this state."
-            required: ["presence"]
-      responses:
-        200:
-          description: The new presence state was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Presence
-    get:
-      summary: Get this user's presence state.
-      description: |-
-        Get the given user's presence state.
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence state to get.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: The presence state for this user.
-          examples:
-            application/json: |-
-              {
-                "presence": "unavailable",
-                "last_active_ago": 420845
-              }
-          schema:
-            type: object
-            properties:
-              presence:
-                type: string
-                enum: ["online", "offline", "unavailable"]
-                description: This user's presence.
-              last_active_ago:
-                type: integer
-                description: |-
-                  The length of time in milliseconds since an action was performed
-                  by this user.
-              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.
-      description: |-
-        Adds or removes users from this presence list.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence list is being modified.
-          required: true
-          x-example: "@alice:example.com"
-        - in: body
-          name: presence_diff
-          description: The modifications to make to this presence list.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "invite": [
-                  "@bob:matrix.org"
-                ],
-                "drop": [
-                  "@alice:matrix.org"
-                ]
-              }
-            properties:
-              invite:
-                type: array
-                description: A list of user IDs to add to the list.
-                items:
-                  type: string
-                  description: A list of user IDs.
-              drop:
-                type: array
-                description: A list of user IDs to remove from the list.
-                items:
-                  type: string
-                  description: A list of user IDs.
-      responses:
-        200:
-          description: The list was updated.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Presence
-    get:
-      summary: Get presence events for this presence list.
-      description: |-
-        Retrieve a list of presence events for every user on this list.
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose presence list should be retrieved.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: A list of presence events for this list.
-          examples:
-            application/json: |-
-              [
-                {
-                  "content": {
-                    "last_active_ago": 395,
-                    "presence": "offline",
-                    "user_id": "@alice:matrix.org"
-                  },
-                  "type": "m.presence"
-                },
-                {
-                  "content": {
-                    "last_active_ago": 16874,
-                    "presence": "online",
-                    "user_id": "@marisa:matrix.org",
-                    "currently_active": true
-                  },
-                  "type": "m.presence"
-                }
-              ]
-          schema:
-            type: array
-            items:
-              type: object
-              title: PresenceEvent
-              allOf:
-                - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
-      tags:
-        - Presence

api/client-server/profile.yaml

@@ -1,214 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Profile 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:
-  "/profile/{userId}/displayname":
-    put:
-      summary: Set the user's display name.
-      description: |-
-        This API sets the given user's display name. You must have permission to
-        set this user's display name, e.g. you need to have their ``access_token``.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose display name to set.
-          required: true
-          x-example: "@alice:example.com"
-        - in: body
-          name: displayName
-          description: The display name info.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "displayname": "Alice Margatroid"
-              }
-            properties:
-              displayname:
-                type: string
-                description: The new display name for this user.
-      responses:
-        200:
-          description: The display name was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - User data
-    get:
-      summary: Get the user's display name.
-      description: |-
-        Get the user's display name. This API may be used to fetch the user's
-        own displayname or to query the name of other users; either locally or
-        on remote homeservers.
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose display name to get.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: The display name for this user.
-          examples:
-            application/json: |-
-              {
-                "displayname": "Alice Margatroid"
-              }
-          schema:
-            type: object
-            properties:
-              displayname:
-                type: string
-                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.
-      description: |-
-        This API sets the given user's avatar URL. You must have permission to
-        set this user's avatar URL, e.g. you need to have their ``access_token``.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose avatar URL to set.
-          required: true
-          x-example: "@alice:example.com"
-        - in: body
-          name: avatar_url
-          description: The avatar url info.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
-              }
-            properties:
-              avatar_url:
-                type: string
-                description: The new avatar URL for this user.
-      responses:
-        200:
-          description: The avatar URL was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - User data
-    get:
-      summary: Get the user's avatar URL.
-      description: |-
-        Get the user's avatar URL. This API may be used to fetch the user's
-        own avatar URL or to query the URL of other users; either locally or
-        on remote homeservers.
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose avatar URL to get.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: The avatar URL for this user.
-          examples:
-            application/json: |-
-              {
-                "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
-              }
-          schema:
-            type: object
-            properties:
-              avatar_url:
-                type: string
-                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.
-      description: |-
-        Get the combined profile information for this user. This API may be used
-        to fetch the user's own profile information or other users; either
-        locally or on remote homeservers. This API may return keys which are not
-        limited to ``displayname`` or ``avatar_url``.
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user whose profile information to get.
-          required: true
-          x-example: "@alice:example.com"
-      responses:
-        200:
-          description: The avatar URL for this user.
-          examples:
-            application/json: |-
-              {
-                "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
-                "displayname": "Alice Margatroid"
-              }
-          schema:
-            type: object
-            properties:
-              avatar_url:
-                type: string
-                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, otherwise not present.
-        404:
-          description: There is no profile information for this user or this user does not exist.
-      tags:
-        - User data

api/client-server/pusher.yaml

@@ -1,238 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Push 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:
-  "/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.
-      description: |-
-        This endpoint allows the creation, modification and deletion of `pushers`_
-        for this user ID. The behaviour of this endpoint varies depending on the
-        values in the JSON body.
-      security:
-        - accessToken: []
-      parameters:
-        - in: body
-          name: pusher
-          description: The pusher information
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "lang": "en",
-                "kind": "http",
-                "app_display_name": "Mat Rix",
-                "device_display_name": "iPhone 9",
-                "profile_tag": "xxyyzz",
-                "app_id": "com.example.app.ios",
-                "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
-                "data": {
-                  "url": "https://push-gateway.location.here"
-                },
-                "append": false
-              }
-            properties:
-              pushkey:
-                type: string
-                description: |-
-                  This is a unique identifier for this pusher. The value you
-                  should use for this is the routing or destination address
-                  information for the notification, for example, the APNS token
-                  for APNS or the Registration ID for GCM. If your notification
-                  client has no such concept, use any unique identifier.
-                  Max length, 512 bytes.
-              kind:
-                type: string
-                description: |-
-                  The kind of pusher to configure. ``"http"`` makes a pusher that
-                  sends HTTP pokes. ``null`` deletes the pusher.
-              app_id:
-                type: string
-                description: |-
-                  This is a reverse-DNS style identifier for the application.
-                  It is recommended that this end with the platform, such that
-                  different platform versions get different app identifiers.
-                  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. If ``kind`` is ``http``, this should contain ``url``
-                  which is the URL to use to send notifications to.
-                title: PusherData
-                properties:
-                  url:
-                    type: string
-                    description: |-
-                      Required if ``kind`` is ``http``. The URL to use to send
-                      notifications to.
-              append:
-                type: boolean
-                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 homeserver must remove any
-                  other pushers with the same App ID and pushkey for different
-                  users. The default is ``false``.
-            required: ['kind', 'app_id', 'app_display_name',
-                'device_display_name', 'pushkey', 'lang', 'data']
-      responses:
-        200:
-          description: The pusher was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        400:
-          description: One or more of the pusher values were invalid.
-          examples:
-            application/json: |-
-              {
-                "error": "Missing parameters: lang, data",
-                "errcode": "M_MISSING_PARAM"
-              }
-          schema:
-            type: object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Push notifications

api/client-server/pushrules.yaml

@@ -1,652 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Push Rules 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:
-  "/pushrules/":
-    get:
-      summary: Retrieve all push rulesets.
-      description: |-
-        Retrieve all push rulesets for this user. Clients can "drill-down" on
-        the rulesets by suffixing a ``scope`` to this path e.g.
-        ``/pushrules/global/``. This will return a subset of this data under the
-        specified key e.g. the ``global`` key.
-      security:
-        - accessToken: []
-      responses:
-        200:
-          description: All the push rulesets for this user.
-          schema:
-            type: object
-            required: ["global"]
-            properties:
-              global:
-                type: object
-                description: The global ruleset.
-                title: Ruleset
-                allOf: [
-                  "$ref": "definitions/push_ruleset.yaml"
-                ]
-          examples:
-            application/json: |-
-              {
-                "global": {
-                    "content": [
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "sound",
-                                    "value": "default"
-                                },
-                                {
-                                    "set_tweak": "highlight"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "pattern": "alice",
-                            "rule_id": ".m.rule.contains_user_name"
-                        }
-                    ],
-                    "override": [
-                        {
-                            "actions": [
-                                "dont_notify"
-                            ],
-                            "conditions": [],
-                            "default": true,
-                            "enabled": false,
-                            "rule_id": ".m.rule.master"
-                        },
-                        {
-                            "actions": [
-                                "dont_notify"
-                            ],
-                            "conditions": [
-                                {
-                                    "key": "content.msgtype",
-                                    "kind": "event_match",
-                                    "pattern": "m.notice"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.suppress_notices"
-                        }
-                    ],
-                    "room": [],
-                    "sender": [],
-                    "underride": [
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "sound",
-                                    "value": "ring"
-                                },
-                                {
-                                    "set_tweak": "highlight",
-                                    "value": false
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "key": "type",
-                                    "kind": "event_match",
-                                    "pattern": "m.call.invite"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.call"
-                        },
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "sound",
-                                    "value": "default"
-                                },
-                                {
-                                    "set_tweak": "highlight"
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "kind": "contains_display_name"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.contains_display_name"
-                        },
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "sound",
-                                    "value": "default"
-                                },
-                                {
-                                    "set_tweak": "highlight",
-                                    "value": false
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "is": "2",
-                                    "kind": "room_member_count"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.room_one_to_one"
-                        },
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "sound",
-                                    "value": "default"
-                                },
-                                {
-                                    "set_tweak": "highlight",
-                                    "value": false
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "key": "type",
-                                    "kind": "event_match",
-                                    "pattern": "m.room.member"
-                                },
-                                {
-                                    "key": "content.membership",
-                                    "kind": "event_match",
-                                    "pattern": "invite"
-                                },
-                                {
-                                    "key": "state_key",
-                                    "kind": "event_match",
-                                    "pattern": "@alice:example.com"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.invite_for_me"
-                        },
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "highlight",
-                                    "value": false
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "key": "type",
-                                    "kind": "event_match",
-                                    "pattern": "m.room.member"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.member_event"
-                        },
-                        {
-                            "actions": [
-                                "notify",
-                                {
-                                    "set_tweak": "highlight",
-                                    "value": false
-                                }
-                            ],
-                            "conditions": [
-                                {
-                                    "key": "type",
-                                    "kind": "event_match",
-                                    "pattern": "m.room.message"
-                                }
-                            ],
-                            "default": true,
-                            "enabled": true,
-                            "rule_id": ".m.rule.message"
-                        }
-                    ]
-                }
-              }
-      tags:
-        - Push notifications
-  "/pushrules/{scope}/{kind}/{ruleId}":
-    get:
-      summary: Retrieve a push rule.
-      description: |-
-        Retrieve a single 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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          description: |
-            The identifier for the rule.
-      responses:
-        200:
-          description: |-
-            The specific push rule. This will also include keys specific to the
-            rule itself such as the rule's ``actions`` and ``conditions`` if set.
-          examples:
-            application/json: |-
-              {
-                "actions": [
-                    "dont_notify"
-                ],
-                "rule_id": "#spam:matrix.org",
-                "enabled": true
-              }
-          schema:
-            type: object
-            description: The push rule.
-            title: PushRule
-            allOf: [
-              "$ref": "definitions/push_rule.yaml"
-            ]
-      tags:
-        - Push notifications
-    delete:
-      summary: Delete a push rule.
-      description: |-
-        This endpoint removes the push rule defined in the path.
-      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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          description: |
-            The identifier for the rule.
-      responses:
-        200:
-          description: The push rule was deleted.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-      tags:
-        - Push notifications
-    put:
-      summary: Add or change a push rule.
-      description: |-
-        This endpoint allows the creation, modification and deletion of pushers
-        for this user ID. The behaviour of this endpoint varies depending on the
-        values in the JSON body.
-      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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          description: |
-            The identifier for the rule.
-        - in: query
-          type: string
-          name: before
-          required: false
-          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 user defined rule.
-            It is not possible to add a rule relative to a predefined server rule.
-        - in: query
-          type: string
-          name: after
-          required: false
-          x-example: anotherRuleId
-          description: |-
-            This makes the new rule the next-less important rule relative to the
-            given user defined rule. It is not possible to add a rule relative
-            to a predefined server rule.
-        - in: body
-          name: pushrule
-          description: |-
-            The push rule data. Additional top-level keys may be present depending
-            on the parameters for the rule ``kind``.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "pattern": "cake*lie",
-                "actions": ["notify"]
-              }
-            properties:
-              actions:
-                type: array
-                description: |-
-                  The action(s) to perform when the conditions for this rule are met.
-                items:
-                  type: string
-                  enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
-                  # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
-              conditions:
-                type: array
-                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.
-                items:
-                  type: object
-                  title: conditions
-                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
-            required: ["actions"]
-      responses:
-        200:
-          description: The pusher was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        400:
-          description: There was a problem configuring this push rule.
-          examples:
-            application/json: |-
-              {
-                "error": "before/after rule not found: someRuleId",
-                "errcode": "M_UNKNOWN"
-              }
-          schema:
-            type: object
-        429:
-          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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          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
-          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: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          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
-          required: true
-          x-example: room
-          enum: ["override", "underride", "sender", "room", "content"]
-          description: |
-            The kind of rule
-        - in: path
-          type: string
-          name: ruleId
-          required: true
-          x-example: "#spam:example.com"
-          description: |
-            The identifier for the rule.
-        - in: body
-          name: body
-          description: |
-            The action(s) to perform when the conditions for this rule are met.
-          required: true
-          schema:
-            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: |-
-              {
-                "actions": ["notify"]
-              }
-      responses:
-        200:
-          description: The actions for the push rule were set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object
-      tags:
-        - Push notifications

api/client-server/receipts.yaml

@@ -1,80 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Receipts 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}/receipt/{receiptType}/{eventId}":
-    post:
-      summary: Send a receipt for the given event ID.
-      description: |-
-        This API updates the marker for the given receipt type to the event ID
-        specified.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room in which to send the event.
-          required: true
-          x-example: "!wefuh21ffskfuh345:example.com"
-        - in: path
-          type: string
-          name: receiptType
-          description: The type of receipt to send.
-          required: true
-          x-example: "m.read"
-          enum: ["m.read"]
-        - in: path
-          type: string
-          name: eventId
-          description: The event ID to acknowledge up to.
-          required: true
-          x-example: "$1924376522eioj:example.com"
-        - in: body
-          name: receipt
-          description: |-
-            Extra receipt information to attach to ``content`` if any. The
-            server will automatically set the ``ts`` field.
-          schema:
-            type: object
-            example: |-
-              {}
-      responses:
-        200:
-          description: The receipt was sent.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Room participation

api/client-server/redaction.yaml

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

@@ -1,322 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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.
-
-      parameters:
-        - in: query
-          name: kind
-          type: string
-          x-example: guest
-          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.
-                "$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
-            required: ["password"]
-      responses:
-        200:
-          description: The account has been registered.
-          examples:
-            application/json: |-
-              {
-                "user_id": "@cheeky_monkey:matrix.org",
-                "access_token": "abc123",
-                "home_server": "matrix.org",
-                "refresh_token": "def456"
-              }
-          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 homeserver on which the account has been registered.
-        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

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

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

@@ -1,146 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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. 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: path
-          type: string
-          name: stateKey
-          description: The state_key for the state to send. Defaults to the empty string.
-          required: true
-          x-example: ""
-        - 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
-  "/rooms/{roomId}/state/{eventType}":
-    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. This endpoint forces the state key to be the empty string.
-
-        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,301 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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}/state/{eventType}/{stateKey}":
-    get:
-      summary: Get the state identified by the type and 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.
-      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"
-        - in: path
-          type: string
-          name: stateKey
-          description: The key of the state to look up.
-          required: true
-          x-example: ""
-      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/{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.
-      description: |-
-        Get the state events for the current state of a room.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room to look up the state for.
-          required: true
-          x-example: "!636q39766251:example.com"
-      responses:
-        200:
-          description: The current state of the room
-          examples:
-            application/json: |-
-              [
-                {
-                    "age": 7148266897,
-                    "content": {
-                        "join_rule": "public"
-                    },
-                    "event_id": "$14259997323TLwtb:example.com",
-                    "origin_server_ts": 1425999732392,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.join_rules",
-                    "sender": "@alice:example.com"
-                },
-                {
-                    "age": 6547561012,
-                    "content": {
-                        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                        "membership": "join"
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
-                    "type": "m.room.member",
-                    "sender": "@alice:example.com"
-                },
-                {
-                    "age": 7148267200,
-                    "content": {
-                        "creator": "@alice:example.com"
-                    },
-                    "event_id": "$14259997320KhbwJ:example.com",
-                    "origin_server_ts": 1425999732089,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.create",
-                    "sender": "@alice:example.com"
-                },
-                {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
-                    "type": "m.room.member",
-                    "sender": "@bob:example.com"
-                },
-                {
-                    "age": 7148267004,
-                    "content": {
-                        "ban": 50,
-                        "events": {
-                            "m.room.name": 100,
-                            "m.room.power_levels": 100
-                         },
-                         "events_default": 0,
-                         "kick": 50,
-                         "redact": 50,
-                         "state_default": 50,
-                         "users": {
-                             "@alice:example.com": 100
-                         },
-                         "users_default": 0
-                    },
-                    "event_id": "$14259997322mqfaq:example.com",
-                    "origin_server_ts": 1425999732285,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "",
-                    "type": "m.room.power_levels",
-                    "sender": "@alice:example.com"
-                }
-              ]
-          schema:
-            type: array
-            title: RoomState
-            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 then this will be the state of the room
-              when they left as a list of events.
-            items:
-              title: StateEvent
-              type: object
-              allOf:
-                - "$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.
-      description:
-        Get the list of members for this room.
-      parameters:
-        - in: path
-          type: string
-          name: roomId
-          description: The room to get the member events for.
-          required: true
-          x-example: "!636q39766251:example.com"
-      responses:
-        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
-            room then this will be the members of the room when you left.
-          examples:
-            application/json: |-
-              {
-                "chunk": [
-                  {
-                    "age": 6547561012,
-                    "content": {
-                      "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
-                      "membership": "join"
-                    },
-                    "event_id": "$1426600438280zExKY:example.com",
-                    "membership": "join",
-                    "origin_server_ts": 1426600438277,
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@alice:example.com",
-                    "type": "m.room.member",
-                    "sender": "@alice:example.com"
-                  },
-                  {
-                    "age": 1622568720,
-                    "content": {
-                        "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
-                        "displayname": "Bob",
-                        "membership": "join"
-                    },
-                    "event_id": "$1431525430134MxlLX:example.com",
-                    "origin_server_ts": 1431525430569,
-                    "replaces_state": "$142652023736BSXcM:example.com",
-                    "room_id": "!636q39766251:example.com",
-                    "state_key": "@bob:example.com",
-                    "type": "m.room.member",
-                    "sender": "@bob:example.com"
-                  }
-                ]
-              }
-          schema:
-            type: object
-            properties:
-              chunk:
-                type: array
-                items:
-                  title: MemberEvent
-                  type: object
-                  allOf:
-                    - "$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

@@ -1,344 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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,345 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server sync API"
-  version: "1.0.0"
-host: localhost:8008
-schemes:
-  - https
-basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
-consumes:
-  - application/json
-produces:
-  - application/json
-securityDefinitions:
-  $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.
-        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:
-        - accessToken: []
-      parameters:
-        - in: query
-          name: filter
-          type: string
-          description: |-
-            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
-          type: string
-          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
-          enum: ["offline"]
-          description: |-
-            Controls whether the client is automatically marked as online by
-            polling this API. If this parameter is omitted then the client is
-            automatically marked as online when it uses this API. Otherwise if
-            the parameter is set to "offline" then the client is not marked as
-            being online when it uses this API.
-          x-example: "offline"
-        - in: query
-          name: timeout
-          type: integer
-          description: |-
-            The maximum time to poll in milliseconds before returning this
-            request.
-          x-example: 30000
-      responses:
-        200:
-          description:
-            The initial snapshot or delta for the client to use to update their
-            state.
-          schema:
-            type: object
-            properties:
-              next_batch:
-                type: string
-                description: |-
-                  The batch token to supply in the ``since`` param of the next
-                  ``/sync`` request.
-              rooms:
-                title: Rooms
-                type: object
-                description: |-
-                  Updates to rooms.
-                properties:
-                  join:
-                    title: Joined Rooms
-                    type: object
-                    description: |-
-                      The rooms that the user has joined.
-                    additionalProperties:
-                      title: Joined Room
-                      type: object
-                      properties:
-                        state:
-                          title: State
-                          type: object
-                          description: |-
-                            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/event_batch.yaml"
-                        timeline:
-                          title: Timeline
-                          type: object
-                          description: |-
-                            The timeline of messages and state changes in the
-                            room.
-                          allOf:
-                            - $ref: "definitions/timeline_batch.yaml"
-                        ephemeral:
-                          title: Ephemeral
-                          type: object
-                          description: |-
-                            The ephemeral events in the room that aren't
-                            recorded in the timeline or state of the room.
-                            e.g. typing.
-                          allOf:
-                            - $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.
-                    additionalProperties:
-                      title: Invited Room
-                      type: object
-                      properties:
-                        invite_state:
-                          title: InviteState
-                          type: object
-                          description: |-
-                            The state of a room that the user has been invited
-                            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
-                            the client has archived the room. Instead the
-                            client should keep two separate copies of the
-                            state: the one from the ``invite_state`` and one
-                            from the archived ``state``. If the client joins
-                            the room then the current state will be given as a
-                            delta against the archived ``state`` not the
-                            ``invite_state``.
-                          allOf:
-                            - $ref: "definitions/event_batch.yaml"
-                  leave:
-                    title: Left rooms
-                    type: object
-                    description: |-
-                      The rooms that the user has left or been banned from.
-                    additionalProperties:
-                      title: Left Room
-                      type: object
-                      properties:
-                        state:
-                          title: State
-                          type: object
-                          description: |-
-                            The state updates for the room up to the start of the timeline.
-                          allOf:
-                            - $ref: "definitions/event_batch.yaml"
-                        timeline:
-                          title: Timeline
-                          type: object
-                          description: |-
-                            The timeline of messages and state changes in the
-                            room up to the point when the user left.
-                          allOf:
-                            - $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.yaml"
-          examples:
-            application/json: |-
-              {
-                "next_batch": "s72595_4483_1934",
-                "presence": {
-                  "events": [
-                    {
-                      "sender": "@alice:example.com",
-                      "type": "m.presence",
-                      "content": {"presence": "online"}
-                    }
-                  ]
-                },
-                "account_data": {
-                  "events": [
-                    {
-                      "type": "org.example.custom.config",
-                      "content": {
-                        "custom_config_key": "custom_config_value"
-                      }
-                    }
-                  ]
-                },
-                "rooms": {
-                  "join": {
-                    "!726s6s6q:example.com": {
-                      "state": {
-                        "events": [
-                          {
-                            "sender": "@alice:example.com",
-                            "type": "m.room.member",
-                            "state_key": "@alice:example.com",
-                            "content": {"membership": "join"},
-                            "origin_server_ts": 1417731086795,
-                            "event_id": "$66697273743031:example.com"
-                          }
-                        ]
-                      },
-                      "timeline": {
-                        "events": [
-                          {
-                            "sender": "@bob:example.com",
-                            "type": "m.room.member",
-                            "state_key": "@bob:example.com",
-                            "content": {"membership": "join"},
-                            "prev_content": {"membership": "invite"},
-                            "origin_server_ts": 1417731086795,
-                            "event_id": "$7365636s6r6432:example.com"
-                          },
-                          {
-                            "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"
-                      },
-                      "ephemeral": {
-                        "events": [
-                          {
-                            "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"
-                            }
-                          }
-                        ]
-                      }
-                    }
-                  },
-                  "invite": {
-                    "!696r7674:example.com": {
-                      "invite_state": {
-                        "events": [
-                          {
-                            "sender": "@alice:example.com",
-                            "type": "m.room.name",
-                            "state_key": "",
-                            "content": {"name": "My Room Name"}
-                          },
-                          {
-                            "sender": "@alice:example.com",
-                            "type": "m.room.member",
-                            "state_key": "@bob:example.com",
-                            "content": {"membership": "invite"}
-                          }
-                        ]
-                      }
-                    }
-                  },
-                  "leave": {}
-                }
-              }
-      tags:
-        - Room participation

api/client-server/tags.yaml

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

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

@@ -1,87 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Typing 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}/typing/{userId}":
-    put:
-      summary: Informs the server that the user has started or stopped typing.
-      description: |-
-        This tells the server that the user is typing for the next N
-        milliseconds where N is the value specified in the ``timeout`` key.
-        Alternatively, if ``typing`` is ``false``, it tells the server that the
-        user has stopped typing.
-      security:
-        - accessToken: []
-      parameters:
-        - in: path
-          type: string
-          name: userId
-          description: The user who has started to type.
-          required: true
-          x-example: "@alice:example.com"
-        - in: path
-          type: string
-          name: roomId
-          description: The room in which the user is typing.
-          required: true
-          x-example: "!wefh3sfukhs:example.com"
-        - in: body
-          name: typingState
-          description: The current typing state.
-          required: true
-          schema:
-            type: object
-            example: |-
-              {
-                "typing": true,
-                "timeout": 30000
-              }
-            properties:
-              typing:
-                type: boolean
-                description: |-
-                  Whether the user is typing or not. If ``false``, the ``timeout``
-                  key can be omitted.
-              timeout:
-                type: integer
-                description: The length of time in milliseconds to mark this user as typing.
-            required: ["typing"]
-      responses:
-        200:
-          description: The new typing state was set.
-          examples:
-            application/json: |-
-              {}
-          schema:
-            type: object  # empty json object
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - Room participation

api/client-server/versions.yaml

@@ -1,54 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix 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,78 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Client-Server Voice over IP 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:
-  "/voip/turnServer":
-    get:
-      summary: Obtain TURN server credentials.
-      description: |-
-        This API provides credentials for the client to use when initiating
-        calls.
-      security:
-        - accessToken: []
-      responses:
-        200:
-          description: The TURN server credentials.
-          examples:
-            application/json: |-
-              {
-                "username":"1443779631:@user:example.com",
-                "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
-                "uris":[
-                  "turn:turn.example.com:3478?transport=udp",
-                  "turn:10.20.30.40:3478?transport=tcp",
-                  "turns:10.20.30.40:443?transport=tcp"
-                ],
-                "ttl":86400
-              }
-          schema:
-            type: object
-            properties:
-              username:
-                type: string
-                description: |-
-                  The username to use.
-              password:
-                type: string
-                description: |-
-                  The password to use.
-              uris:
-                type: array
-                items:
-                  type: string
-                description: A list of TURN URIs
-              ttl:
-                type: integer
-                description: The time-to-live in seconds
-            required: ["username", "password", "uris", "ttl"]
-        429:
-          description: This request was rate-limited.
-          schema:
-            "$ref": "definitions/error.yaml"
-      tags:
-        - VOIP

api/files/backbone-min.js

@@ -1,38 +0,0 @@
-// Backbone.js 0.9.2
-
-// (c) 2010-2012 Jeremy Ashkenas, DocumentCloud Inc.
-// Backbone may be freely distributed under the MIT license.
-// For all details and documentation:
-// http://backbonejs.org
-(function(){var l=this,y=l.Backbone,z=Array.prototype.slice,A=Array.prototype.splice,g;g="undefined"!==typeof exports?exports:l.Backbone={};g.VERSION="0.9.2";var f=l._;!f&&"undefined"!==typeof require&&(f=require("underscore"));var i=l.jQuery||l.Zepto||l.ender;g.setDomLibrary=function(a){i=a};g.noConflict=function(){l.Backbone=y;return this};g.emulateHTTP=!1;g.emulateJSON=!1;var p=/\s+/,k=g.Events={on:function(a,b,c){var d,e,f,g,j;if(!b)return this;a=a.split(p);for(d=this._callbacks||(this._callbacks=
-{});e=a.shift();)f=(j=d[e])?j.tail:{},f.next=g={},f.context=c,f.callback=b,d[e]={tail:g,next:j?j.next:f};return this},off:function(a,b,c){var d,e,h,g,j,q;if(e=this._callbacks){if(!a&&!b&&!c)return delete this._callbacks,this;for(a=a?a.split(p):f.keys(e);d=a.shift();)if(h=e[d],delete e[d],h&&(b||c))for(g=h.tail;(h=h.next)!==g;)if(j=h.callback,q=h.context,b&&j!==b||c&&q!==c)this.on(d,j,q);return this}},trigger:function(a){var b,c,d,e,f,g;if(!(d=this._callbacks))return this;f=d.all;a=a.split(p);for(g=
-z.call(arguments,1);b=a.shift();){if(c=d[b])for(e=c.tail;(c=c.next)!==e;)c.callback.apply(c.context||this,g);if(c=f){e=c.tail;for(b=[b].concat(g);(c=c.next)!==e;)c.callback.apply(c.context||this,b)}}return this}};k.bind=k.on;k.unbind=k.off;var o=g.Model=function(a,b){var c;a||(a={});b&&b.parse&&(a=this.parse(a));if(c=n(this,"defaults"))a=f.extend({},c,a);b&&b.collection&&(this.collection=b.collection);this.attributes={};this._escapedAttributes={};this.cid=f.uniqueId("c");this.changed={};this._silent=
-{};this._pending={};this.set(a,{silent:!0});this.changed={};this._silent={};this._pending={};this._previousAttributes=f.clone(this.attributes);this.initialize.apply(this,arguments)};f.extend(o.prototype,k,{changed:null,_silent:null,_pending:null,idAttribute:"id",initialize:function(){},toJSON:function(){return f.clone(this.attributes)},get:function(a){return this.attributes[a]},escape:function(a){var b;if(b=this._escapedAttributes[a])return b;b=this.get(a);return this._escapedAttributes[a]=f.escape(null==
-b?"":""+b)},has:function(a){return null!=this.get(a)},set:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c||(c={});if(!d)return this;d instanceof o&&(d=d.attributes);if(c.unset)for(e in d)d[e]=void 0;if(!this._validate(d,c))return!1;this.idAttribute in d&&(this.id=d[this.idAttribute]);var b=c.changes={},h=this.attributes,g=this._escapedAttributes,j=this._previousAttributes||{};for(e in d){a=d[e];if(!f.isEqual(h[e],a)||c.unset&&f.has(h,e))delete g[e],(c.silent?this._silent:
-b)[e]=!0;c.unset?delete h[e]:h[e]=a;!f.isEqual(j[e],a)||f.has(h,e)!=f.has(j,e)?(this.changed[e]=a,c.silent||(this._pending[e]=!0)):(delete this.changed[e],delete this._pending[e])}c.silent||this.change(c);return this},unset:function(a,b){(b||(b={})).unset=!0;return this.set(a,null,b)},clear:function(a){(a||(a={})).unset=!0;return this.set(f.clone(this.attributes),a)},fetch:function(a){var a=a?f.clone(a):{},b=this,c=a.success;a.success=function(d,e,f){if(!b.set(b.parse(d,f),a))return!1;c&&c(b,d)};
-a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},save:function(a,b,c){var d,e;f.isObject(a)||null==a?(d=a,c=b):(d={},d[a]=b);c=c?f.clone(c):{};if(c.wait){if(!this._validate(d,c))return!1;e=f.clone(this.attributes)}a=f.extend({},c,{silent:!0});if(d&&!this.set(d,c.wait?a:c))return!1;var h=this,i=c.success;c.success=function(a,b,e){b=h.parse(a,e);if(c.wait){delete c.wait;b=f.extend(d||{},b)}if(!h.set(b,c))return false;i?i(h,a):h.trigger("sync",h,a,c)};c.error=g.wrapError(c.error,
-h,c);b=this.isNew()?"create":"update";b=(this.sync||g.sync).call(this,b,this,c);c.wait&&this.set(e,a);return b},destroy:function(a){var a=a?f.clone(a):{},b=this,c=a.success,d=function(){b.trigger("destroy",b,b.collection,a)};if(this.isNew())return d(),!1;a.success=function(e){a.wait&&d();c?c(b,e):b.trigger("sync",b,e,a)};a.error=g.wrapError(a.error,b,a);var e=(this.sync||g.sync).call(this,"delete",this,a);a.wait||d();return e},url:function(){var a=n(this,"urlRoot")||n(this.collection,"url")||t();
-return this.isNew()?a:a+("/"==a.charAt(a.length-1)?"":"/")+encodeURIComponent(this.id)},parse:function(a){return a},clone:function(){return new this.constructor(this.attributes)},isNew:function(){return null==this.id},change:function(a){a||(a={});var b=this._changing;this._changing=!0;for(var c in this._silent)this._pending[c]=!0;var d=f.extend({},a.changes,this._silent);this._silent={};for(c in d)this.trigger("change:"+c,this,this.get(c),a);if(b)return this;for(;!f.isEmpty(this._pending);){this._pending=
-{};this.trigger("change",this,a);for(c in this.changed)!this._pending[c]&&!this._silent[c]&&delete this.changed[c];this._previousAttributes=f.clone(this.attributes)}this._changing=!1;return this},hasChanged:function(a){return!arguments.length?!f.isEmpty(this.changed):f.has(this.changed,a)},changedAttributes:function(a){if(!a)return this.hasChanged()?f.clone(this.changed):!1;var b,c=!1,d=this._previousAttributes,e;for(e in a)if(!f.isEqual(d[e],b=a[e]))(c||(c={}))[e]=b;return c},previous:function(a){return!arguments.length||
-!this._previousAttributes?null:this._previousAttributes[a]},previousAttributes:function(){return f.clone(this._previousAttributes)},isValid:function(){return!this.validate(this.attributes)},_validate:function(a,b){if(b.silent||!this.validate)return!0;var a=f.extend({},this.attributes,a),c=this.validate(a,b);if(!c)return!0;b&&b.error?b.error(this,c,b):this.trigger("error",this,c,b);return!1}});var r=g.Collection=function(a,b){b||(b={});b.model&&(this.model=b.model);b.comparator&&(this.comparator=b.comparator);
-this._reset();this.initialize.apply(this,arguments);a&&this.reset(a,{silent:!0,parse:b.parse})};f.extend(r.prototype,k,{model:o,initialize:function(){},toJSON:function(a){return this.map(function(b){return b.toJSON(a)})},add:function(a,b){var c,d,e,g,i,j={},k={},l=[];b||(b={});a=f.isArray(a)?a.slice():[a];c=0;for(d=a.length;c<d;c++){if(!(e=a[c]=this._prepareModel(a[c],b)))throw Error("Can't add an invalid model to a collection");g=e.cid;i=e.id;j[g]||this._byCid[g]||null!=i&&(k[i]||this._byId[i])?
-l.push(c):j[g]=k[i]=e}for(c=l.length;c--;)a.splice(l[c],1);c=0;for(d=a.length;c<d;c++)(e=a[c]).on("all",this._onModelEvent,this),this._byCid[e.cid]=e,null!=e.id&&(this._byId[e.id]=e);this.length+=d;A.apply(this.models,[null!=b.at?b.at:this.models.length,0].concat(a));this.comparator&&this.sort({silent:!0});if(b.silent)return this;c=0;for(d=this.models.length;c<d;c++)if(j[(e=this.models[c]).cid])b.index=c,e.trigger("add",e,this,b);return this},remove:function(a,b){var c,d,e,g;b||(b={});a=f.isArray(a)?
-a.slice():[a];c=0;for(d=a.length;c<d;c++)if(g=this.getByCid(a[c])||this.get(a[c]))delete this._byId[g.id],delete this._byCid[g.cid],e=this.indexOf(g),this.models.splice(e,1),this.length--,b.silent||(b.index=e,g.trigger("remove",g,this,b)),this._removeReference(g);return this},push:function(a,b){a=this._prepareModel(a,b);this.add(a,b);return a},pop:function(a){var b=this.at(this.length-1);this.remove(b,a);return b},unshift:function(a,b){a=this._prepareModel(a,b);this.add(a,f.extend({at:0},b));return a},
-shift:function(a){var b=this.at(0);this.remove(b,a);return b},get:function(a){return null==a?void 0:this._byId[null!=a.id?a.id:a]},getByCid:function(a){return a&&this._byCid[a.cid||a]},at:function(a){return this.models[a]},where:function(a){return f.isEmpty(a)?[]:this.filter(function(b){for(var c in a)if(a[c]!==b.get(c))return!1;return!0})},sort:function(a){a||(a={});if(!this.comparator)throw Error("Cannot sort a set without a comparator");var b=f.bind(this.comparator,this);1==this.comparator.length?
-this.models=this.sortBy(b):this.models.sort(b);a.silent||this.trigger("reset",this,a);return this},pluck:function(a){return f.map(this.models,function(b){return b.get(a)})},reset:function(a,b){a||(a=[]);b||(b={});for(var c=0,d=this.models.length;c<d;c++)this._removeReference(this.models[c]);this._reset();this.add(a,f.extend({silent:!0},b));b.silent||this.trigger("reset",this,b);return this},fetch:function(a){a=a?f.clone(a):{};void 0===a.parse&&(a.parse=!0);var b=this,c=a.success;a.success=function(d,
-e,f){b[a.add?"add":"reset"](b.parse(d,f),a);c&&c(b,d)};a.error=g.wrapError(a.error,b,a);return(this.sync||g.sync).call(this,"read",this,a)},create:function(a,b){var c=this,b=b?f.clone(b):{},a=this._prepareModel(a,b);if(!a)return!1;b.wait||c.add(a,b);var d=b.success;b.success=function(e,f){b.wait&&c.add(e,b);d?d(e,f):e.trigger("sync",a,f,b)};a.save(null,b);return a},parse:function(a){return a},chain:function(){return f(this.models).chain()},_reset:function(){this.length=0;this.models=[];this._byId=
-{};this._byCid={}},_prepareModel:function(a,b){b||(b={});a instanceof o?a.collection||(a.collection=this):(b.collection=this,a=new this.model(a,b),a._validate(a.attributes,b)||(a=!1));return a},_removeReference:function(a){this==a.collection&&delete a.collection;a.off("all",this._onModelEvent,this)},_onModelEvent:function(a,b,c,d){("add"==a||"remove"==a)&&c!=this||("destroy"==a&&this.remove(b,d),b&&a==="change:"+b.idAttribute&&(delete this._byId[b.previous(b.idAttribute)],this._byId[b.id]=b),this.trigger.apply(this,
-arguments))}});f.each("forEach,each,map,reduce,reduceRight,find,detect,filter,select,reject,every,all,some,any,include,contains,invoke,max,min,sortBy,sortedIndex,toArray,size,first,initial,rest,last,without,indexOf,shuffle,lastIndexOf,isEmpty,groupBy".split(","),function(a){r.prototype[a]=function(){return f[a].apply(f,[this.models].concat(f.toArray(arguments)))}});var u=g.Router=function(a){a||(a={});a.routes&&(this.routes=a.routes);this._bindRoutes();this.initialize.apply(this,arguments)},B=/:\w+/g,
-C=/\*\w+/g,D=/[-[\]{}()+?.,\\^$|#\s]/g;f.extend(u.prototype,k,{initialize:function(){},route:function(a,b,c){g.history||(g.history=new m);f.isRegExp(a)||(a=this._routeToRegExp(a));c||(c=this[b]);g.history.route(a,f.bind(function(d){d=this._extractParameters(a,d);c&&c.apply(this,d);this.trigger.apply(this,["route:"+b].concat(d));g.history.trigger("route",this,b,d)},this));return this},navigate:function(a,b){g.history.navigate(a,b)},_bindRoutes:function(){if(this.routes){var a=[],b;for(b in this.routes)a.unshift([b,
-this.routes[b]]);b=0;for(var c=a.length;b<c;b++)this.route(a[b][0],a[b][1],this[a[b][1]])}},_routeToRegExp:function(a){a=a.replace(D,"\\$&").replace(B,"([^/]+)").replace(C,"(.*?)");return RegExp("^"+a+"$")},_extractParameters:function(a,b){return a.exec(b).slice(1)}});var m=g.History=function(){this.handlers=[];f.bindAll(this,"checkUrl")},s=/^[#\/]/,E=/msie [\w.]+/;m.started=!1;f.extend(m.prototype,k,{interval:50,getHash:function(a){return(a=(a?a.location:window.location).href.match(/#(.*)$/))?a[1]:
-""},getFragment:function(a,b){if(null==a)if(this._hasPushState||b){var a=window.location.pathname,c=window.location.search;c&&(a+=c)}else a=this.getHash();a.indexOf(this.options.root)||(a=a.substr(this.options.root.length));return a.replace(s,"")},start:function(a){if(m.started)throw Error("Backbone.history has already been started");m.started=!0;this.options=f.extend({},{root:"/"},this.options,a);this._wantsHashChange=!1!==this.options.hashChange;this._wantsPushState=!!this.options.pushState;this._hasPushState=
-!(!this.options.pushState||!window.history||!window.history.pushState);var a=this.getFragment(),b=document.documentMode;if(b=E.exec(navigator.userAgent.toLowerCase())&&(!b||7>=b))this.iframe=i('<iframe src="javascript:0" tabindex="-1" />').hide().appendTo("body")[0].contentWindow,this.navigate(a);this._hasPushState?i(window).bind("popstate",this.checkUrl):this._wantsHashChange&&"onhashchange"in window&&!b?i(window).bind("hashchange",this.checkUrl):this._wantsHashChange&&(this._checkUrlInterval=setInterval(this.checkUrl,
-this.interval));this.fragment=a;a=window.location;b=a.pathname==this.options.root;if(this._wantsHashChange&&this._wantsPushState&&!this._hasPushState&&!b)return this.fragment=this.getFragment(null,!0),window.location.replace(this.options.root+"#"+this.fragment),!0;this._wantsPushState&&this._hasPushState&&b&&a.hash&&(this.fragment=this.getHash().replace(s,""),window.history.replaceState({},document.title,a.protocol+"//"+a.host+this.options.root+this.fragment));if(!this.options.silent)return this.loadUrl()},
-stop:function(){i(window).unbind("popstate",this.checkUrl).unbind("hashchange",this.checkUrl);clearInterval(this._checkUrlInterval);m.started=!1},route:function(a,b){this.handlers.unshift({route:a,callback:b})},checkUrl:function(){var a=this.getFragment();a==this.fragment&&this.iframe&&(a=this.getFragment(this.getHash(this.iframe)));if(a==this.fragment)return!1;this.iframe&&this.navigate(a);this.loadUrl()||this.loadUrl(this.getHash())},loadUrl:function(a){var b=this.fragment=this.getFragment(a);return f.any(this.handlers,
-function(a){if(a.route.test(b))return a.callback(b),!0})},navigate:function(a,b){if(!m.started)return!1;if(!b||!0===b)b={trigger:b};var c=(a||"").replace(s,"");this.fragment!=c&&(this._hasPushState?(0!=c.indexOf(this.options.root)&&(c=this.options.root+c),this.fragment=c,window.history[b.replace?"replaceState":"pushState"]({},document.title,c)):this._wantsHashChange?(this.fragment=c,this._updateHash(window.location,c,b.replace),this.iframe&&c!=this.getFragment(this.getHash(this.iframe))&&(b.replace||
-this.iframe.document.open().close(),this._updateHash(this.iframe.location,c,b.replace))):window.location.assign(this.options.root+a),b.trigger&&this.loadUrl(a))},_updateHash:function(a,b,c){c?a.replace(a.toString().replace(/(javascript:|#).*$/,"")+"#"+b):a.hash=b}});var v=g.View=function(a){this.cid=f.uniqueId("view");this._configure(a||{});this._ensureElement();this.initialize.apply(this,arguments);this.delegateEvents()},F=/^(\S+)\s*(.*)$/,w="model,collection,el,id,attributes,className,tagName".split(",");
-f.extend(v.prototype,k,{tagName:"div",$:function(a){return this.$el.find(a)},initialize:function(){},render:function(){return this},remove:function(){this.$el.remove();return this},make:function(a,b,c){a=document.createElement(a);b&&i(a).attr(b);c&&i(a).html(c);return a},setElement:function(a,b){this.$el&&this.undelegateEvents();this.$el=a instanceof i?a:i(a);this.el=this.$el[0];!1!==b&&this.delegateEvents();return this},delegateEvents:function(a){if(a||(a=n(this,"events"))){this.undelegateEvents();
-for(var b in a){var c=a[b];f.isFunction(c)||(c=this[a[b]]);if(!c)throw Error('Method "'+a[b]+'" does not exist');var d=b.match(F),e=d[1],d=d[2],c=f.bind(c,this),e=e+(".delegateEvents"+this.cid);""===d?this.$el.bind(e,c):this.$el.delegate(d,e,c)}}},undelegateEvents:function(){this.$el.unbind(".delegateEvents"+this.cid)},_configure:function(a){this.options&&(a=f.extend({},this.options,a));for(var b=0,c=w.length;b<c;b++){var d=w[b];a[d]&&(this[d]=a[d])}this.options=a},_ensureElement:function(){if(this.el)this.setElement(this.el,
-!1);else{var a=n(this,"attributes")||{};this.id&&(a.id=this.id);this.className&&(a["class"]=this.className);this.setElement(this.make(this.tagName,a),!1)}}});o.extend=r.extend=u.extend=v.extend=function(a,b){var c=G(this,a,b);c.extend=this.extend;return c};var H={create:"POST",update:"PUT","delete":"DELETE",read:"GET"};g.sync=function(a,b,c){var d=H[a];c||(c={});var e={type:d,dataType:"json"};c.url||(e.url=n(b,"url")||t());if(!c.data&&b&&("create"==a||"update"==a))e.contentType="application/json",
-e.data=JSON.stringify(b.toJSON());g.emulateJSON&&(e.contentType="application/x-www-form-urlencoded",e.data=e.data?{model:e.data}:{});if(g.emulateHTTP&&("PUT"===d||"DELETE"===d))g.emulateJSON&&(e.data._method=d),e.type="POST",e.beforeSend=function(a){a.setRequestHeader("X-HTTP-Method-Override",d)};"GET"!==e.type&&!g.emulateJSON&&(e.processData=!1);return i.ajax(f.extend(e,c))};g.wrapError=function(a,b,c){return function(d,e){e=d===b?e:d;a?a(b,e,c):b.trigger("error",b,e,c)}};var x=function(){},G=function(a,
-b,c){var d;d=b&&b.hasOwnProperty("constructor")?b.constructor:function(){a.apply(this,arguments)};f.extend(d,a);x.prototype=a.prototype;d.prototype=new x;b&&f.extend(d.prototype,b);c&&f.extend(d,c);d.prototype.constructor=d;d.__super__=a.prototype;return d},n=function(a,b){return!a||!a[b]?null:f.isFunction(a[b])?a[b]():a[b]},t=function(){throw Error('A "url" property or function must be specified');}}).call(this);

api/files/css

@@ -1,16 +0,0 @@
-/* latin */
-@font-face {
-  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');
-  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 */
-@font-face {
-  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');
-  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/files/jquery.ba-bbq.min.js

@@ -1,18 +0,0 @@
-/*
- * jQuery BBQ: Back Button & Query Library - v1.2.1 - 2/17/2010
- * http://benalman.com/projects/jquery-bbq-plugin/
- * 
- * Copyright (c) 2010 "Cowboy" Ben Alman
- * Dual licensed under the MIT and GPL licenses.
- * http://benalman.com/about/license/
- */
-(function($,p){var i,m=Array.prototype.slice,r=decodeURIComponent,a=$.param,c,l,v,b=$.bbq=$.bbq||{},q,u,j,e=$.event.special,d="hashchange",A="querystring",D="fragment",y="elemUrlAttr",g="location",k="href",t="src",x=/^.*\?|#.*$/g,w=/^.*\#/,h,C={};function E(F){return typeof F==="string"}function B(G){var F=m.call(arguments,1);return function(){return G.apply(this,F.concat(m.call(arguments)))}}function n(F){return F.replace(/^[^#]*#?(.*)$/,"$1")}function o(F){return F.replace(/(?:^[^?#]*\?([^#]*).*$)?.*/,"$1")}function f(H,M,F,I,G){var O,L,K,N,J;if(I!==i){K=F.match(H?/^([^#]*)\#?(.*)$/:/^([^#?]*)\??([^#]*)(#?.*)/);J=K[3]||"";if(G===2&&E(I)){L=I.replace(H?w:x,"")}else{N=l(K[2]);I=E(I)?l[H?D:A](I):I;L=G===2?I:G===1?$.extend({},I,N):$.extend({},N,I);L=a(L);if(H){L=L.replace(h,r)}}O=K[1]+(H?"#":L||!K[1]?"?":"")+L+J}else{O=M(F!==i?F:p[g][k])}return O}a[A]=B(f,0,o);a[D]=c=B(f,1,n);c.noEscape=function(G){G=G||"";var F=$.map(G.split(""),encodeURIComponent);h=new RegExp(F.join("|"),"g")};c.noEscape(",/");$.deparam=l=function(I,F){var H={},G={"true":!0,"false":!1,"null":null};$.each(I.replace(/\+/g," ").split("&"),function(L,Q){var K=Q.split("="),P=r(K[0]),J,O=H,M=0,R=P.split("]["),N=R.length-1;if(/\[/.test(R[0])&&/\]$/.test(R[N])){R[N]=R[N].replace(/\]$/,"");R=R.shift().split("[").concat(R);N=R.length-1}else{N=0}if(K.length===2){J=r(K[1]);if(F){J=J&&!isNaN(J)?+J:J==="undefined"?i:G[J]!==i?G[J]:J}if(N){for(;M<=N;M++){P=R[M]===""?O.length:R[M];O=O[P]=M<N?O[P]||(R[M+1]&&isNaN(R[M+1])?{}:[]):J}}else{if($.isArray(H[P])){H[P].push(J)}else{if(H[P]!==i){H[P]=[H[P],J]}else{H[P]=J}}}}else{if(P){H[P]=F?i:""}}});return H};function z(H,F,G){if(F===i||typeof F==="boolean"){G=F;F=a[H?D:A]()}else{F=E(F)?F.replace(H?w:x,""):F}return l(F,G)}l[A]=B(z,0);l[D]=v=B(z,1);$[y]||($[y]=function(F){return $.extend(C,F)})({a:k,base:k,iframe:t,img:t,input:t,form:"action",link:k,script:t});j=$[y];function s(I,G,H,F){if(!E(H)&&typeof H!=="object"){F=H;H=G;G=i}return this.each(function(){var L=$(this),J=G||j()[(this.nodeName||"").toLowerCase()]||"",K=J&&L.attr(J)||"";L.attr(J,a[I](K,H,F))})}$.fn[A]=B(s,A);$.fn[D]=B(s,D);b.pushState=q=function(I,F){if(E(I)&&/^#/.test(I)&&F===i){F=2}var H=I!==i,G=c(p[g][k],H?I:{},H?F:2);p[g][k]=G+(/#/.test(G)?"":"#")};b.getState=u=function(F,G){return F===i||typeof F==="boolean"?v(F):v(G)[F]};b.removeState=function(F){var G={};if(F!==i){G=u();$.each($.isArray(F)?F:arguments,function(I,H){delete G[H]})}q(G,2)};e[d]=$.extend(e[d],{add:function(F){var H;function G(J){var I=J[D]=c();J.getState=function(K,L){return K===i||typeof K==="boolean"?l(I,K):l(I,L)[K]};H.apply(this,arguments)}if($.isFunction(F)){H=F;return G}else{H=F.handler;F.handler=G}}})})(jQuery,this);
-/*
- * jQuery hashchange event - v1.2 - 2/11/2010
- * http://benalman.com/projects/jquery-hashchange-plugin/
- * 
- * Copyright (c) 2010 "Cowboy" Ben Alman
- * Dual licensed under the MIT and GPL licenses.
- * http://benalman.com/about/license/
- */
-(function($,i,b){var j,k=$.event.special,c="location",d="hashchange",l="href",f=$.browser,g=document.documentMode,h=f.msie&&(g===b||g<8),e="on"+d in i&&!h;function a(m){m=m||i[c][l];return m.replace(/^[^#]*#?(.*)$/,"$1")}$[d+"Delay"]=100;k[d]=$.extend(k[d],{setup:function(){if(e){return false}$(j.start)},teardown:function(){if(e){return false}$(j.stop)}});j=(function(){var m={},r,n,o,q;function p(){o=q=function(s){return s};if(h){n=$('<iframe src="javascript:0"/>').hide().insertAfter("body")[0].contentWindow;q=function(){return a(n.document[c][l])};o=function(u,s){if(u!==s){var t=n.document;t.open().close();t[c].hash="#"+u}};o(a())}}m.start=function(){if(r){return}var t=a();o||p();(function s(){var v=a(),u=q(t);if(v!==t){o(t=v,u);$(i).trigger(d)}else{if(u!==t){i[c][l]=i[c][l].replace(/#.*/,"")+"#"+u}}r=setTimeout(s,$[d+"Delay"])})()};m.stop=function(){if(!n){r&&clearTimeout(r);r=0}};return m})()})(jQuery,this);

api/files/jquery.slideto.min.js

@@ -1 +0,0 @@
-(function(b){b.fn.slideto=function(a){a=b.extend({slide_duration:"slow",highlight_duration:3E3,highlight:true,highlight_color:"#FFFF99"},a);return this.each(function(){obj=b(this);b("body").animate({scrollTop:obj.offset().top},a.slide_duration,function(){a.highlight&&b.ui.version&&obj.effect("highlight",{color:a.highlight_color},a.highlight_duration)})})}})(jQuery);

api/files/jquery.wiggle.min.js

@@ -1,8 +0,0 @@
-/*
-jQuery Wiggle
-Author: WonderGroup, Jordan Thomas
-URL: http://labs.wondergroup.com/demos/mini-ui/index.html
-License: MIT (http://en.wikipedia.org/wiki/MIT_License)
-*/
-jQuery.fn.wiggle=function(o){var d={speed:50,wiggles:3,travel:5,callback:null};var o=jQuery.extend(d,o);return this.each(function(){var cache=this;var wrap=jQuery(this).wrap('<div class="wiggle-wrap"></div>').css("position","relative");var calls=0;for(i=1;i<=o.wiggles;i++){jQuery(this).animate({left:"-="+o.travel},o.speed).animate({left:"+="+o.travel*2},o.speed*2).animate({left:"-="+o.travel},o.speed,function(){calls++;if(jQuery(cache).parent().hasClass('wiggle-wrap')){jQuery(cache).parent().replaceWith(cache);}
-if(calls==o.wiggles&&jQuery.isFunction(o.callback)){o.callback();}});}});};

api/files/reset.css

@@ -1,125 +0,0 @@
-/* http://meyerweb.com/eric/tools/css/reset/ v2.0 | 20110126 */
-html,
-body,
-div,
-span,
-applet,
-object,
-iframe,
-h1,
-h2,
-h3,
-h4,
-h5,
-h6,
-p,
-blockquote,
-pre,
-a,
-abbr,
-acronym,
-address,
-big,
-cite,
-code,
-del,
-dfn,
-em,
-img,
-ins,
-kbd,
-q,
-s,
-samp,
-small,
-strike,
-strong,
-sub,
-sup,
-tt,
-var,
-b,
-u,
-i,
-center,
-dl,
-dt,
-dd,
-ol,
-ul,
-li,
-fieldset,
-form,
-label,
-legend,
-table,
-caption,
-tbody,
-tfoot,
-thead,
-tr,
-th,
-td,
-article,
-aside,
-canvas,
-details,
-embed,
-figure,
-figcaption,
-footer,
-header,
-hgroup,
-menu,
-nav,
-output,
-ruby,
-section,
-summary,
-time,
-mark,
-audio,
-video {
-  margin: 0;
-  padding: 0;
-  border: 0;
-  font-size: 100%;
-  font: inherit;
-  vertical-align: baseline;
-}
-/* HTML5 display-role reset for older browsers */
-article,
-aside,
-details,
-figcaption,
-figure,
-footer,
-header,
-hgroup,
-menu,
-nav,
-section {
-  display: block;
-}
-body {
-  line-height: 1;
-}
-ol,
-ul {
-  list-style: none;
-}
-blockquote,
-q {
-  quotes: none;
-}
-blockquote:before,
-blockquote:after,
-q:before,
-q:after {
-  content: '';
-  content: none;
-}
-table {
-  border-collapse: collapse;
-  border-spacing: 0;
-}

api/files/swagger-oauth.js

@@ -1,211 +0,0 @@
-var appName;
-var popupMask;
-var popupDialog;
-var clientId;
-var realm;
-
-function handleLogin() {
-  var scopes = [];
-
-  if(window.swaggerUi.api.authSchemes 
-    && window.swaggerUi.api.authSchemes.oauth2
-    && window.swaggerUi.api.authSchemes.oauth2.scopes) {
-    scopes = window.swaggerUi.api.authSchemes.oauth2.scopes;
-  }
-
-  if(window.swaggerUi.api
-    && window.swaggerUi.api.info) {
-    appName = window.swaggerUi.api.info.title;
-  }
-
-  if(popupDialog.length > 0)
-    popupDialog = popupDialog.last();
-  else {
-    popupDialog = $(
-      [
-        '<div class="api-popup-dialog">',
-        '<div class="api-popup-title">Select OAuth2.0 Scopes</div>',
-        '<div class="api-popup-content">',
-          '<p>Scopes are used to grant an application different levels of access to data on behalf of the end user. Each API may declare one or more scopes.',
-            '<a href="#">Learn how to use</a>',
-          '</p>',
-          '<p><strong>' + appName + '</strong> API requires the following scopes. Select which ones you want to grant to Swagger UI.</p>',
-          '<ul class="api-popup-scopes">',
-          '</ul>',
-          '<p class="error-msg"></p>',
-          '<div class="api-popup-actions"><button class="api-popup-authbtn api-button green" type="button">Authorize</button><button class="api-popup-cancel api-button gray" type="button">Cancel</button></div>',
-        '</div>',
-        '</div>'].join(''));
-    $(document.body).append(popupDialog);
-
-    popup = popupDialog.find('ul.api-popup-scopes').empty();
-    for (i = 0; i < scopes.length; i ++) {
-      scope = scopes[i];
-      str = '<li><input type="checkbox" id="scope_' + i + '" scope="' + scope.scope + '"/>' + '<label for="scope_' + i + '">' + scope.scope;
-      if (scope.description) {
-        str += '<br/><span class="api-scope-desc">' + scope.description + '</span>';
-      }
-      str += '</label></li>';
-      popup.append(str);
-    }
-  }
-
-  var $win = $(window),
-    dw = $win.width(),
-    dh = $win.height(),
-    st = $win.scrollTop(),
-    dlgWd = popupDialog.outerWidth(),
-    dlgHt = popupDialog.outerHeight(),
-    top = (dh -dlgHt)/2 + st,
-    left = (dw - dlgWd)/2;
-
-  popupDialog.css({
-    top: (top < 0? 0 : top) + 'px',
-    left: (left < 0? 0 : left) + 'px'
-  });
-
-  popupDialog.find('button.api-popup-cancel').click(function() {
-    popupMask.hide();
-    popupDialog.hide();
-  });
-  popupDialog.find('button.api-popup-authbtn').click(function() {
-    popupMask.hide();
-    popupDialog.hide();
-
-    var authSchemes = window.swaggerUi.api.authSchemes;
-    var host = window.location;
-    var redirectUrl = host.protocol + '//' + host.host + "/o2c.html";
-    var url = null;
-
-    var p = window.swaggerUi.api.authSchemes;
-    for (var key in p) {
-      if (p.hasOwnProperty(key)) {
-        var o = p[key].grantTypes;
-        for(var t in o) {
-          if(o.hasOwnProperty(t) && t === 'implicit') {
-            var dets = o[t];
-            url = dets.loginEndpoint.url + "?response_type=token";
-            window.swaggerUi.tokenName = dets.tokenName;
-          }
-        }
-      }
-    }
-    var scopes = []
-    var o = $('.api-popup-scopes').find('input:checked');
-
-    for(k =0; k < o.length; k++) {
-      scopes.push($(o[k]).attr("scope"));
-    }
-
-    window.enabledScopes=scopes;
-
-    url += '&redirect_uri=' + encodeURIComponent(redirectUrl);
-    url += '&realm=' + encodeURIComponent(realm);
-    url += '&client_id=' + encodeURIComponent(clientId);
-    url += '&scope=' + encodeURIComponent(scopes);
-
-    window.open(url);
-  });
-
-  popupMask.show();
-  popupDialog.show();
-  return;
-}
-
-
-function handleLogout() {
-  for(key in window.authorizations.authz){
-    window.authorizations.remove(key)
-  }
-  window.enabledScopes = null;
-  $('.api-ic.ic-on').addClass('ic-off');
-  $('.api-ic.ic-on').removeClass('ic-on');
-
-  // set the info box
-  $('.api-ic.ic-warning').addClass('ic-error');
-  $('.api-ic.ic-warning').removeClass('ic-warning');
-}
-
-function initOAuth(opts) {
-  var o = (opts||{});
-  var errors = [];
-
-  appName = (o.appName||errors.push("missing appName"));
-  popupMask = (o.popupMask||$('#api-common-mask'));
-  popupDialog = (o.popupDialog||$('.api-popup-dialog'));
-  clientId = (o.clientId||errors.push("missing client id"));
-  realm = (o.realm||errors.push("missing realm"));
-
-  if(errors.length > 0){
-    log("auth unable initialize oauth: " + errors);
-    return;
-  }
-
-  $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
-  $('.api-ic').click(function(s) {
-    if($(s.target).hasClass('ic-off'))
-      handleLogin();
-    else {
-      handleLogout();
-    }
-    false;
-  });
-}
-
-function onOAuthComplete(token) {
-  if(token) {
-    if(token.error) {
-      var checkbox = $('input[type=checkbox],.secured')
-      checkbox.each(function(pos){
-        checkbox[pos].checked = false;
-      });
-      alert(token.error);
-    }
-    else {
-      var b = token[window.swaggerUi.tokenName];
-      if(b){
-        // if all roles are satisfied
-        var o = null;
-        $.each($('.auth #api_information_panel'), function(k, v) {
-          var children = v;
-          if(children && children.childNodes) {
-            var requiredScopes = [];
-            $.each((children.childNodes), function (k1, v1){
-              var inner = v1.innerHTML;
-              if(inner)
-                requiredScopes.push(inner);
-            });
-            var diff = [];
-            for(var i=0; i < requiredScopes.length; i++) {
-              var s = requiredScopes[i];
-              if(window.enabledScopes && window.enabledScopes.indexOf(s) == -1) {
-                diff.push(s);
-              }
-            }
-            if(diff.length > 0){
-              o = v.parentNode;
-              $(o.parentNode).find('.api-ic.ic-on').addClass('ic-off');
-              $(o.parentNode).find('.api-ic.ic-on').removeClass('ic-on');
-
-              // sorry, not all scopes are satisfied
-              $(o).find('.api-ic').addClass('ic-warning');
-              $(o).find('.api-ic').removeClass('ic-error');
-            }
-            else {
-              o = v.parentNode;
-              $(o.parentNode).find('.api-ic.ic-off').addClass('ic-on');
-              $(o.parentNode).find('.api-ic.ic-off').removeClass('ic-off');
-
-              // all scopes are satisfied
-              $(o).find('.api-ic').addClass('ic-info');
-              $(o).find('.api-ic').removeClass('ic-warning');
-              $(o).find('.api-ic').removeClass('ic-error');          
-            }
-          }
-        });
-
-        window.authorizations.add("oauth2", new ApiKeyAuthorization("Authorization", "Bearer " + b, "header"));
-      }
-    }
-  }
-}

api/files/underscore-min.js

@@ -1,32 +0,0 @@
-// Underscore.js 1.3.3
-// (c) 2009-2012 Jeremy Ashkenas, DocumentCloud Inc.
-// Underscore is freely distributable under the MIT license.
-// Portions of Underscore are inspired or borrowed from Prototype,
-// Oliver Steele's Functional, and John Resig's Micro-Templating.
-// For all details and documentation:
-// http://documentcloud.github.com/underscore
-(function(){function r(a,c,d){if(a===c)return 0!==a||1/a==1/c;if(null==a||null==c)return a===c;a._chain&&(a=a._wrapped);c._chain&&(c=c._wrapped);if(a.isEqual&&b.isFunction(a.isEqual))return a.isEqual(c);if(c.isEqual&&b.isFunction(c.isEqual))return c.isEqual(a);var e=l.call(a);if(e!=l.call(c))return!1;switch(e){case "[object String]":return a==""+c;case "[object Number]":return a!=+a?c!=+c:0==a?1/a==1/c:a==+c;case "[object Date]":case "[object Boolean]":return+a==+c;case "[object RegExp]":return a.source==
-c.source&&a.global==c.global&&a.multiline==c.multiline&&a.ignoreCase==c.ignoreCase}if("object"!=typeof a||"object"!=typeof c)return!1;for(var f=d.length;f--;)if(d[f]==a)return!0;d.push(a);var f=0,g=!0;if("[object Array]"==e){if(f=a.length,g=f==c.length)for(;f--&&(g=f in a==f in c&&r(a[f],c[f],d)););}else{if("constructor"in a!="constructor"in c||a.constructor!=c.constructor)return!1;for(var h in a)if(b.has(a,h)&&(f++,!(g=b.has(c,h)&&r(a[h],c[h],d))))break;if(g){for(h in c)if(b.has(c,h)&&!f--)break;
-g=!f}}d.pop();return g}var s=this,I=s._,o={},k=Array.prototype,p=Object.prototype,i=k.slice,J=k.unshift,l=p.toString,K=p.hasOwnProperty,y=k.forEach,z=k.map,A=k.reduce,B=k.reduceRight,C=k.filter,D=k.every,E=k.some,q=k.indexOf,F=k.lastIndexOf,p=Array.isArray,L=Object.keys,t=Function.prototype.bind,b=function(a){return new m(a)};"undefined"!==typeof exports?("undefined"!==typeof module&&module.exports&&(exports=module.exports=b),exports._=b):s._=b;b.VERSION="1.3.3";var j=b.each=b.forEach=function(a,
-c,d){if(a!=null)if(y&&a.forEach===y)a.forEach(c,d);else if(a.length===+a.length)for(var e=0,f=a.length;e<f;e++){if(e in a&&c.call(d,a[e],e,a)===o)break}else for(e in a)if(b.has(a,e)&&c.call(d,a[e],e,a)===o)break};b.map=b.collect=function(a,c,b){var e=[];if(a==null)return e;if(z&&a.map===z)return a.map(c,b);j(a,function(a,g,h){e[e.length]=c.call(b,a,g,h)});if(a.length===+a.length)e.length=a.length;return e};b.reduce=b.foldl=b.inject=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(A&&
-a.reduce===A){e&&(c=b.bind(c,e));return f?a.reduce(c,d):a.reduce(c)}j(a,function(a,b,i){if(f)d=c.call(e,d,a,b,i);else{d=a;f=true}});if(!f)throw new TypeError("Reduce of empty array with no initial value");return d};b.reduceRight=b.foldr=function(a,c,d,e){var f=arguments.length>2;a==null&&(a=[]);if(B&&a.reduceRight===B){e&&(c=b.bind(c,e));return f?a.reduceRight(c,d):a.reduceRight(c)}var g=b.toArray(a).reverse();e&&!f&&(c=b.bind(c,e));return f?b.reduce(g,c,d,e):b.reduce(g,c)};b.find=b.detect=function(a,
-c,b){var e;G(a,function(a,g,h){if(c.call(b,a,g,h)){e=a;return true}});return e};b.filter=b.select=function(a,c,b){var e=[];if(a==null)return e;if(C&&a.filter===C)return a.filter(c,b);j(a,function(a,g,h){c.call(b,a,g,h)&&(e[e.length]=a)});return e};b.reject=function(a,c,b){var e=[];if(a==null)return e;j(a,function(a,g,h){c.call(b,a,g,h)||(e[e.length]=a)});return e};b.every=b.all=function(a,c,b){var e=true;if(a==null)return e;if(D&&a.every===D)return a.every(c,b);j(a,function(a,g,h){if(!(e=e&&c.call(b,
-a,g,h)))return o});return!!e};var G=b.some=b.any=function(a,c,d){c||(c=b.identity);var e=false;if(a==null)return e;if(E&&a.some===E)return a.some(c,d);j(a,function(a,b,h){if(e||(e=c.call(d,a,b,h)))return o});return!!e};b.include=b.contains=function(a,c){var b=false;if(a==null)return b;if(q&&a.indexOf===q)return a.indexOf(c)!=-1;return b=G(a,function(a){return a===c})};b.invoke=function(a,c){var d=i.call(arguments,2);return b.map(a,function(a){return(b.isFunction(c)?c||a:a[c]).apply(a,d)})};b.pluck=
-function(a,c){return b.map(a,function(a){return a[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a)&&a[0]===+a[0])return Math.max.apply(Math,a);if(!c&&b.isEmpty(a))return-Infinity;var e={computed:-Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b>=e.computed&&(e={value:a,computed:b})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a)&&a[0]===+a[0])return Math.min.apply(Math,a);if(!c&&b.isEmpty(a))return Infinity;var e={computed:Infinity};j(a,function(a,b,h){b=c?c.call(d,a,b,h):a;b<e.computed&&
-(e={value:a,computed:b})});return e.value};b.shuffle=function(a){var b=[],d;j(a,function(a,f){d=Math.floor(Math.random()*(f+1));b[f]=b[d];b[d]=a});return b};b.sortBy=function(a,c,d){var e=b.isFunction(c)?c:function(a){return a[c]};return b.pluck(b.map(a,function(a,b,c){return{value:a,criteria:e.call(d,a,b,c)}}).sort(function(a,b){var c=a.criteria,d=b.criteria;return c===void 0?1:d===void 0?-1:c<d?-1:c>d?1:0}),"value")};b.groupBy=function(a,c){var d={},e=b.isFunction(c)?c:function(a){return a[c]};
-j(a,function(a,b){var c=e(a,b);(d[c]||(d[c]=[])).push(a)});return d};b.sortedIndex=function(a,c,d){d||(d=b.identity);for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?e=g+1:f=g}return e};b.toArray=function(a){return!a?[]:b.isArray(a)||b.isArguments(a)?i.call(a):a.toArray&&b.isFunction(a.toArray)?a.toArray():b.values(a)};b.size=function(a){return b.isArray(a)?a.length:b.keys(a).length};b.first=b.head=b.take=function(a,b,d){return b!=null&&!d?i.call(a,0,b):a[0]};b.initial=function(a,b,d){return i.call(a,
-0,a.length-(b==null||d?1:b))};b.last=function(a,b,d){return b!=null&&!d?i.call(a,Math.max(a.length-b,0)):a[a.length-1]};b.rest=b.tail=function(a,b,d){return i.call(a,b==null||d?1:b)};b.compact=function(a){return b.filter(a,function(a){return!!a})};b.flatten=function(a,c){return b.reduce(a,function(a,e){if(b.isArray(e))return a.concat(c?e:b.flatten(e));a[a.length]=e;return a},[])};b.without=function(a){return b.difference(a,i.call(arguments,1))};b.uniq=b.unique=function(a,c,d){var d=d?b.map(a,d):a,
-e=[];a.length<3&&(c=true);b.reduce(d,function(d,g,h){if(c?b.last(d)!==g||!d.length:!b.include(d,g)){d.push(g);e.push(a[h])}return d},[]);return e};b.union=function(){return b.uniq(b.flatten(arguments,true))};b.intersection=b.intersect=function(a){var c=i.call(arguments,1);return b.filter(b.uniq(a),function(a){return b.every(c,function(c){return b.indexOf(c,a)>=0})})};b.difference=function(a){var c=b.flatten(i.call(arguments,1),true);return b.filter(a,function(a){return!b.include(c,a)})};b.zip=function(){for(var a=
-i.call(arguments),c=b.max(b.pluck(a,"length")),d=Array(c),e=0;e<c;e++)d[e]=b.pluck(a,""+e);return d};b.indexOf=function(a,c,d){if(a==null)return-1;var e;if(d){d=b.sortedIndex(a,c);return a[d]===c?d:-1}if(q&&a.indexOf===q)return a.indexOf(c);d=0;for(e=a.length;d<e;d++)if(d in a&&a[d]===c)return d;return-1};b.lastIndexOf=function(a,b){if(a==null)return-1;if(F&&a.lastIndexOf===F)return a.lastIndexOf(b);for(var d=a.length;d--;)if(d in a&&a[d]===b)return d;return-1};b.range=function(a,b,d){if(arguments.length<=
-1){b=a||0;a=0}for(var d=arguments[2]||1,e=Math.max(Math.ceil((b-a)/d),0),f=0,g=Array(e);f<e;){g[f++]=a;a=a+d}return g};var H=function(){};b.bind=function(a,c){var d,e;if(a.bind===t&&t)return t.apply(a,i.call(arguments,1));if(!b.isFunction(a))throw new TypeError;e=i.call(arguments,2);return d=function(){if(!(this instanceof d))return a.apply(c,e.concat(i.call(arguments)));H.prototype=a.prototype;var b=new H,g=a.apply(b,e.concat(i.call(arguments)));return Object(g)===g?g:b}};b.bindAll=function(a){var c=
-i.call(arguments,1);c.length==0&&(c=b.functions(a));j(c,function(c){a[c]=b.bind(a[c],a)});return a};b.memoize=function(a,c){var d={};c||(c=b.identity);return function(){var e=c.apply(this,arguments);return b.has(d,e)?d[e]:d[e]=a.apply(this,arguments)}};b.delay=function(a,b){var d=i.call(arguments,2);return setTimeout(function(){return a.apply(null,d)},b)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(i.call(arguments,1)))};b.throttle=function(a,c){var d,e,f,g,h,i,j=b.debounce(function(){h=
-g=false},c);return function(){d=this;e=arguments;f||(f=setTimeout(function(){f=null;h&&a.apply(d,e);j()},c));g?h=true:i=a.apply(d,e);j();g=true;return i}};b.debounce=function(a,b,d){var e;return function(){var f=this,g=arguments;d&&!e&&a.apply(f,g);clearTimeout(e);e=setTimeout(function(){e=null;d||a.apply(f,g)},b)}};b.once=function(a){var b=false,d;return function(){if(b)return d;b=true;return d=a.apply(this,arguments)}};b.wrap=function(a,b){return function(){var d=[a].concat(i.call(arguments,0));
-return b.apply(this,d)}};b.compose=function(){var a=arguments;return function(){for(var b=arguments,d=a.length-1;d>=0;d--)b=[a[d].apply(this,b)];return b[0]}};b.after=function(a,b){return a<=0?b():function(){if(--a<1)return b.apply(this,arguments)}};b.keys=L||function(a){if(a!==Object(a))throw new TypeError("Invalid object");var c=[],d;for(d in a)b.has(a,d)&&(c[c.length]=d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=b.methods=function(a){var c=[],d;for(d in a)b.isFunction(a[d])&&
-c.push(d);return c.sort()};b.extend=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]=b[d]});return a};b.pick=function(a){var c={};j(b.flatten(i.call(arguments,1)),function(b){b in a&&(c[b]=a[b])});return c};b.defaults=function(a){j(i.call(arguments,1),function(b){for(var d in b)a[d]==null&&(a[d]=b[d])});return a};b.clone=function(a){return!b.isObject(a)?a:b.isArray(a)?a.slice():b.extend({},a)};b.tap=function(a,b){b(a);return a};b.isEqual=function(a,b){return r(a,b,[])};b.isEmpty=
-function(a){if(a==null)return true;if(b.isArray(a)||b.isString(a))return a.length===0;for(var c in a)if(b.has(a,c))return false;return true};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=p||function(a){return l.call(a)=="[object Array]"};b.isObject=function(a){return a===Object(a)};b.isArguments=function(a){return l.call(a)=="[object Arguments]"};b.isArguments(arguments)||(b.isArguments=function(a){return!(!a||!b.has(a,"callee"))});b.isFunction=function(a){return l.call(a)=="[object Function]"};
-b.isString=function(a){return l.call(a)=="[object String]"};b.isNumber=function(a){return l.call(a)=="[object Number]"};b.isFinite=function(a){return b.isNumber(a)&&isFinite(a)};b.isNaN=function(a){return a!==a};b.isBoolean=function(a){return a===true||a===false||l.call(a)=="[object Boolean]"};b.isDate=function(a){return l.call(a)=="[object Date]"};b.isRegExp=function(a){return l.call(a)=="[object RegExp]"};b.isNull=function(a){return a===null};b.isUndefined=function(a){return a===void 0};b.has=function(a,
-b){return K.call(a,b)};b.noConflict=function(){s._=I;return this};b.identity=function(a){return a};b.times=function(a,b,d){for(var e=0;e<a;e++)b.call(d,e)};b.escape=function(a){return(""+a).replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#x27;").replace(/\//g,"&#x2F;")};b.result=function(a,c){if(a==null)return null;var d=a[c];return b.isFunction(d)?d.call(a):d};b.mixin=function(a){j(b.functions(a),function(c){M(c,b[c]=a[c])})};var N=0;b.uniqueId=
-function(a){var b=N++;return a?a+b:b};b.templateSettings={evaluate:/<%([\s\S]+?)%>/g,interpolate:/<%=([\s\S]+?)%>/g,escape:/<%-([\s\S]+?)%>/g};var u=/.^/,n={"\\":"\\","'":"'",r:"\r",n:"\n",t:"\t",u2028:"\u2028",u2029:"\u2029"},v;for(v in n)n[n[v]]=v;var O=/\\|'|\r|\n|\t|\u2028|\u2029/g,P=/\\(\\|'|r|n|t|u2028|u2029)/g,w=function(a){return a.replace(P,function(a,b){return n[b]})};b.template=function(a,c,d){d=b.defaults(d||{},b.templateSettings);a="__p+='"+a.replace(O,function(a){return"\\"+n[a]}).replace(d.escape||
-u,function(a,b){return"'+\n_.escape("+w(b)+")+\n'"}).replace(d.interpolate||u,function(a,b){return"'+\n("+w(b)+")+\n'"}).replace(d.evaluate||u,function(a,b){return"';\n"+w(b)+"\n;__p+='"})+"';\n";d.variable||(a="with(obj||{}){\n"+a+"}\n");var a="var __p='';var print=function(){__p+=Array.prototype.join.call(arguments, '')};\n"+a+"return __p;\n",e=new Function(d.variable||"obj","_",a);if(c)return e(c,b);c=function(a){return e.call(this,a,b)};c.source="function("+(d.variable||"obj")+"){\n"+a+"}";return c};
-b.chain=function(a){return b(a).chain()};var m=function(a){this._wrapped=a};b.prototype=m.prototype;var x=function(a,c){return c?b(a).chain():a},M=function(a,c){m.prototype[a]=function(){var a=i.call(arguments);J.call(a,this._wrapped);return x(c.apply(b,a),this._chain)}};b.mixin(b);j("pop,push,reverse,shift,sort,splice,unshift".split(","),function(a){var b=k[a];m.prototype[a]=function(){var d=this._wrapped;b.apply(d,arguments);var e=d.length;(a=="shift"||a=="splice")&&e===0&&delete d[0];return x(d,
-this._chain)}});j(["concat","join","slice"],function(a){var b=k[a];m.prototype[a]=function(){return x(b.apply(this._wrapped,arguments),this._chain)}});m.prototype.chain=function(){this._chain=true;return this};m.prototype.value=function(){return this._wrapped}}).call(this);

api/identity/lookup.yaml

@@ -1,86 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Identity Service Lookup  API"
-  version: "1.0.0"
-host: localhost:8090
-schemes:
-  - https
-  - http
-basePath: /_matrix/identity/v1/api
-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

@@ -1,110 +0,0 @@
-# Copyright 2016 OpenMarket Ltd
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-swagger: '2.0'
-info:
-  title: "Matrix Identity Service Public Key API"
-  version: "1.0.0"
-host: localhost:8090
-schemes:
-  - https
-  - http
-basePath: /_matrix/identity/v1/api
-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/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "swagger-cli-validator",
-  "version": "0.0.1",
-  "description": "",
-  "main": "validator.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "",
-  "license": "ISC",
-  "dependencies": {
-    "nopt": "^3.0.2",
-    "swagger-parser": "^3.2.1"
-  }
-}

api/push-gateway/push_notifier.yaml

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

@@ -1,71 +0,0 @@
-"use strict";
-var fs = require("fs");
-var nopt = require("nopt");
-var parser = require("swagger-parser");
-var path = require("path");
-
-var opts = nopt({
-    "help": Boolean,
-    "schema": path
-}, {
-    "h": "--help",
-    "s": "--schema"
-});
-
-if (opts.help) {
-    console.log(
-        "Use swagger-parser to validate against Swagger 2.0\n"+
-        "Usage:\n"+
-        "  node validator.js -s <schema_file_or_folder>"
-    );
-    process.exit(0);
-}
-if (!opts.schema) {
-    console.error("No [s]chema specified.");
-    process.exit(1);
-}
-
-
-var errFn = function(err, api) {
-    if (!err) {
-        return;
-    }
-    console.error(err);
-    process.exit(1);
-};
-
-var isDir = fs.lstatSync(opts.schema).isDirectory()
-if (isDir) {
-    console.log("Checking directory %s for .yaml files...", opts.schema);
-    fs.readdir(opts.schema, function(err, files) {
-        if (err) {
-            console.error(err);
-            process.exit(1);
-        }
-        files.forEach(function(f) {
-            var suffix = ".yaml";
-            if (f.indexOf(suffix, f.length - suffix.length) > 0) {
-                parser.validate(path.join(opts.schema, f), function(err, api, metadata) {
-                    if (!err) {
-                        console.log("%s is valid.", f);
-                    }
-                    else {
-                        console.error("%s is not valid.", f);
-                        errFn(err, api, metadata);
-                    }
-                });
-            } 
-        });
-    });
-}
-else{
-    parser.validate(opts.schema, function(err, api) {
-        if (!err) {
-            console.log("%s is valid", opts.schema);
-        }
-        else {
-            errFn(err, api);
-        }
-    });
-};
-

attic/v1_registration_login.rst

@@ -1,343 +0,0 @@
-Registration and Login
-----------------------
-
-Clients must register with a homeserver in order to use Matrix. After
-registering, the client will be given an access token which must be used in ALL
-requests to that homeserver as a query parameter 'access_token'.
-
-If the client has already registered, they need to be able to login to their
-account. The homeserver may provide many different ways of logging in, such as
-user/password auth, login via a social network (OAuth2), login by confirming a
-token sent to their email address, etc. This specification does not define how
-homeservers should authorise their users who want to login to their existing
-accounts, but instead defines the standard interface which implementations
-should follow so that ANY client can login to ANY homeserver. Clients login
-using the |login|_ API. Clients register using the |register|_ API.
-Registration follows the same general procedure as login, but the path requests
-are sent to and the details contained in them are different.
-
-In both registration and login cases, the process takes the form of one or more
-stages, where at each stage the client submits a set of data for a given stage
-type and awaits a response from the server, which will either be a final
-success or a request to perform an additional stage. This exchange continues
-until the final success.
-
-In order to determine up-front what the server's requirements are, the client
-can request from the server a complete description of all of its acceptable
-flows of the registration or login process. It can then inspect the list of
-returned flows looking for one for which it believes it can complete all of the
-required stages, and perform it. As each homeserver may have different ways of
-logging in, the client needs to know how they should login. All distinct login
-stages MUST have a corresponding ``type``. A ``type`` is a namespaced string
-which details the mechanism for logging in.
-
-A client may be able to login via multiple valid login flows, and should choose
-a single flow when logging in. A flow is a series of login stages. The home
-server MUST respond with all the valid login flows when requested by a simple
-``GET`` request directly to the ``/login`` or ``/register`` paths::
-
-  {
-    "flows": [
-      {
-        "type": "<login type1a>",
-        "stages": [ "<login type 1a>", "<login type 1b>" ]
-      },
-      {
-        "type": "<login type2a>",
-        "stages": [ "<login type 2a>", "<login type 2b>" ]
-      },
-      {
-        "type": "<login type3>"
-      }
-    ]
-  }
-
-The client can now select which flow it wishes to use, and begin making
-``POST`` requests to the ``/login`` or ``/register`` paths with JSON body
-content containing the name of the stage as the ``type`` key, along with
-whatever additional parameters are required for that login or registration type
-(see below). After the flow is completed, the client's fully-qualified user
-ID and a new access token MUST be returned::
-
-  {
-    "user_id": "@user:matrix.org",
-    "access_token": "abcdef0123456789"
-  }
-
-The ``user_id`` key is particularly useful if the homeserver wishes to support
-localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as
-the client may not be able to determine its ``user_id`` in this case.
-
-If the flow has multiple stages to it, the homeserver may wish to create a
-session to store context between requests. If a homeserver responds with a
-``session`` key to a request, clients MUST submit it in subsequent requests
-until the flow is completed::
-
-  {
-    "session": "<session id>"
-  }
-
-This specification defines the following login types:
- - ``m.login.password``
- - ``m.login.oauth2``
- - ``m.login.email.code``
- - ``m.login.email.url``
- - ``m.login.email.identity``
-
-Password-based
-~~~~~~~~~~~~~~
-:Type:
-  ``m.login.password``
-:Description:
-  Login is supported via a username and password.
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.password",
-    "user": "<user_id or user localpart>",
-    "password": "<password>"
-  }
-
-The homeserver MUST respond with either new credentials, the next stage of the
-login process, or a standard error response.
-
-Captcha-based
-~~~~~~~~~~~~~
-:Type:
-  ``m.login.recaptcha``
-:Description:
-  Login is supported by responding to a captcha (in the case of the Synapse
-  implementation, Google's Recaptcha library is used).
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.recaptcha",
-    "challenge": "<challenge token>",
-    "response": "<user-entered text>"
-  }
-
-.. NOTE::
-  In Synapse, the Recaptcha parameters can be obtained in Javascript by calling:
-    Recaptcha.get_challenge();
-    Recaptcha.get_response();
-
-The homeserver MUST respond with either new credentials, the next stage of the
-login process, or a standard error response.
-
-OAuth2-based
-~~~~~~~~~~~~
-:Type:
-  ``m.login.oauth2``
-:Description:
-  Login is supported via OAuth2 URLs. This login consists of multiple requests.
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.oauth2",
-    "user": "<user_id or user localpart>"
-  }
-
-The server MUST respond with::
-
-  {
-    "uri": <Authorization Request URI OR service selection URI>
-  }
-
-The homeserver acts as a 'confidential' client for the purposes of OAuth2.  If
-the uri is a ``sevice selection URI``, it MUST point to a webpage which prompts
-the user to choose which service to authorize with. On selection of a service,
-this MUST link through to an ``Authorization Request URI``. If there is only 1
-service which the homeserver accepts when logging in, this indirection can be
-skipped and the "uri" key can be the ``Authorization Request URI``.
-
-The client then visits the ``Authorization Request URI``, which then shows the
-OAuth2 Allow/Deny prompt. Hitting 'Allow' returns the ``redirect URI`` with the
-auth code.  Homeservers can choose any path for the ``redirect URI``. The
-client should visit the ``redirect URI``, which will then finish the OAuth2
-login process, granting the homeserver an access token for the chosen service.
-When the homeserver gets this access token, it verifies that the cilent has
-authorised with the 3rd party, and can now complete the login. The OAuth2
-``redirect URI`` (with auth code) MUST respond with either new credentials, the
-next stage of the login process, or a standard error response.
-
-For example, if a homeserver accepts OAuth2 from Google, it would return the
-Authorization Request URI for Google::
-
-  {
-    "uri": "https://accounts.google.com/o/oauth2/auth?response_type=code&
-    client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
-  }
-
-The client then visits this URI and authorizes the homeserver. The client then
-visits the REDIRECT_URI with the auth code= query parameter which returns::
-
-  {
-    "user_id": "@user:matrix.org",
-    "access_token": "0123456789abcdef"
-  }
-
-Email-based (code)
-~~~~~~~~~~~~~~~~~~
-:Type:
-  ``m.login.email.code``
-:Description:
-  Login is supported by typing in a code which is sent in an email. This login
-  consists of multiple requests.
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.email.code",
-    "user": "<user_id or user localpart>",
-    "email": "<email address>"
-  }
-
-After validating the email address, the homeserver MUST send an email
-containing an authentication code and return::
-
-  {
-    "type": "m.login.email.code",
-    "session": "<session id>"
-  }
-
-The second request in this login stage involves sending this authentication
-code::
-
-  {
-    "type": "m.login.email.code",
-    "session": "<session id>",
-    "code": "<code in email sent>"
-  }
-
-The homeserver MUST respond to this with either new credentials, the next
-stage of the login process, or a standard error response.
-
-Email-based (url)
-~~~~~~~~~~~~~~~~~
-:Type:
-  ``m.login.email.url``
-:Description:
-  Login is supported by clicking on a URL in an email. This login consists of
-  multiple requests.
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.email.url",
-    "user": "<user_id or user localpart>",
-    "email": "<email address>"
-  }
-
-After validating the email address, the homeserver MUST send an email
-containing an authentication URL and return::
-
-  {
-    "type": "m.login.email.url",
-    "session": "<session id>"
-  }
-
-The email contains a URL which must be clicked. After it has been clicked, the
-client should perform another request::
-
-  {
-    "type": "m.login.email.url",
-    "session": "<session id>"
-  }
-
-The homeserver MUST respond to this with either new credentials, the next
-stage of the login process, or a standard error response.
-
-A common client implementation will be to periodically poll until the link is
-clicked.  If the link has not been visited yet, a standard error response with
-an errcode of ``M_LOGIN_EMAIL_URL_NOT_YET`` should be returned.
-
-
-Email-based (identity server)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-:Type:
-  ``m.login.email.identity``
-:Description:
-  Login is supported by authorising an email address with an identity server.
-
-Prior to submitting this, the client should authenticate with an identity
-server.  After authenticating, the session information should be submitted to
-the homeserver.
-
-To respond to this type, reply with::
-
-  {
-    "type": "m.login.email.identity",
-    "threepidCreds": [
-      {
-        "sid": "<identity server session id>",
-        "clientSecret": "<identity server client secret>",
-        "idServer": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
-      }
-    ]
-  }
-
-
-
-N-Factor Authentication
-~~~~~~~~~~~~~~~~~~~~~~~
-Multiple login stages can be combined to create N-factor authentication during
-login.
-
-This can be achieved by responding with the ``next`` login type on completion
-of a previous login stage::
-
-  {
-    "next": "<next login type>"
-  }
-
-If a homeserver implements N-factor authentication, it MUST respond with all
-``stages`` when initially queried for their login requirements::
-
-  {
-    "type": "<1st login type>",
-    "stages": [ <1st login type>, <2nd login type>, ... , <Nth login type> ]
-  }
-
-This can be represented conceptually as::
-
-   _______________________
-  |    Login Stage 1      |
-  | type: "<login type1>" |
-  |  ___________________  |
-  | |_Request_1_________| | <-- Returns "session" key which is used throughout.
-  |  ___________________  |
-  | |_Request_2_________| | <-- Returns a "next" value of "login type2"
-  |_______________________|
-            |
-            |
-   _________V_____________
-  |    Login Stage 2      |
-  | type: "<login type2>" |
-  |  ___________________  |
-  | |_Request_1_________| |
-  |  ___________________  |
-  | |_Request_2_________| |
-  |  ___________________  |
-  | |_Request_3_________| | <-- Returns a "next" value of "login type3"
-  |_______________________|
-            |
-            |
-   _________V_____________
-  |    Login Stage 3      |
-  | type: "<login type3>" |
-  |  ___________________  |
-  | |_Request_1_________| | <-- Returns user credentials
-  |_______________________|
-
-Fallback
-~~~~~~~~
-Clients cannot be expected to be able to know how to process every single login
-type. If a client determines it does not know how to handle a given login type,
-it should request a login fallback page::
-
-  GET matrix/client/api/v1/login/fallback
-
-This MUST return an HTML page which can perform the entire login process.

changelogs/client_server.rst

@@ -1,195 +0,0 @@
-r0.2.0
-======
-
-- Spec clarifications
-
-  - Room aliases (`#337 <https://github.com/matrix-org/matrix-doc/pull/337>`_):
-
-    - Make it clear that ``GET /directory/room/{roomAlias}`` must work for
-      federated aliases.
-
-    - ``GET /directory/room/{roomAlias}`` cannot return a 409; the ``PUT``
-      endpoint can, however.
-
-  - Power levels:
-
-    - Clarify the defaults to be used for various fields of the
-      ``m.room.power_levels`` event
-      (`#286 <https://github.com/matrix-org/matrix-doc/pull/286>`_,
-      `#341 <https://github.com/matrix-org/matrix-doc/pull/341>`_).
-
-    - Add suggestions for mapping of names to power levels
-      (`#336 <https://github.com/matrix-org/matrix-doc/pull/336>`_).
-
-  - Clarify the room naming algorithm in certain edge cases
-    (`#351 <https://github.com/matrix-org/matrix-doc/pull/351>`_).
-
-  - Remove outdated references to the pre-r0 ``/events`` API, and clarify the
-    section on syncing
-    (`#352 <https://github.com/matrix-org/matrix-doc/pull/352>`_).
-
-
-- Changes to the API which will be backwards-compatible for clients:
-
-  - New endpoints:
-
-    - ``POST /register/email/requestToken``
-      (`#343 <https://github.com/matrix-org/matrix-doc/pull/343>`_).
-
-    - ``POST /account/3pid/email/requestToken``
-      (`#346 <https://github.com/matrix-org/matrix-doc/pull/346>`_).
-
-    - ``POST /account/password/email/requestToken``
-      (`#346 <https://github.com/matrix-org/matrix-doc/pull/346>`_).
-
-    - ``POST /account/deactivate``
-      (`#361 <https://github.com/matrix-org/matrix-doc/pull/361>`_).
-
-  - Updates to the Presence module
-    (`#278 <https://github.com/matrix-org/matrix-doc/pull/278>`_,
-    `#342 <https://github.com/matrix-org/matrix-doc/pull/342>`_):
-
-    - Remove unused ``free_for_chat`` presence state
-    - Add ``currently_active`` flag to the ``m.presence`` event and the ``GET
-      /presence/{userId}/status`` response.
-    - Make idle timeout the responsibility of the server
-    - Remove requirements on servers to propagate profile information via
-      ``m.presence`` events.
-
-  - Add new predefined push rules
-    (`#274 <https://github.com/matrix-org/matrix-doc/pull/274>`_,
-    `#340 <https://github.com/matrix-org/matrix-doc/pull/340/files>`_).
-
-  - ``/sync`` should always return a ``prev_batch`` token
-    (`#345 <https://github.com/matrix-org/matrix-doc/pull/345>`_).
-
-  - add ``to`` parameter to ``GET /rooms/{roomId}/messages`` API
-    (`#348 <https://github.com/matrix-org/matrix-doc/pull/348>`_).
-
-r0.1.0
-======
-
-This release includes the following changes since r0.0.1:
-
-- Breaking changes to the API [#]_:
-
-  - ``POST /rooms/{roomId}/join`` no longer permits use of a room alias instead
-    of a room id. (``POST /join/{roomIdOrAlias}`` continues to allow either.)
-  - ``POST /account/3pid``: correct the name of the ``three_pid_creds``
-    parameter
-  - The "Push Rules" module no longer supports device-specific rules:
-
-    - ``GET /pushrules`` no longer returns a ``device`` property
-    - ``device/{profile_tag}`` is no longer a valid ``scope`` for push rules
-    - ``profile_tag`` is no longer a valid kind of condition on push rules.
-
-    (Device-specific push rules will be reintroduced in the future; in the
-    meantime, their specification has been moved to a `draft branch`__.)
-
-    __ https://matrix.org/speculator/spec/drafts%2Freinstate_device_push_rules/
-
-- Changes to the API which will be backwards-compatible for clients:
-
-  - New endpoints:
-
-    - ``POST /logout``
-    - ``POST /rooms/{roomId}/unban``
-    - ``POST /rooms/{roomId}/kick``
-    - ``GET /pushers``
-    - ``GET /pushrules/{scope}/{kind}/{ruleId}/enabled``
-      (previously ``PUT``-only)
-    - ``GET`` and ``PUT /pushrules/{scope}/{kind}/{ruleId}/actions``
-
-  - Add ``third_party_signed`` parameter to ``POST /rooms/{roomId}/join``
-  - Add ``M_INVALID_USERNAME`` as valid response to ``POST /register``
-  - Add ``unread_notifications`` field to ``GET /sync`` response
-  - Add optional ``invite`` property to ``m.room.power_levels`` state event
-  - Add optional ``public_key`` and ``public_keys`` to
-    ``m.room.third_party_invite`` state event
-  - Password-based ``/login`` may now use a third-party identifier instead of
-    a matrix user id.
-
-- Spec clarifications
-
-  - Make the state diagram for room membership explicit
-  - Note that a user may not be invited to a room while banned
-  - Clarify the expected order of events in the response to
-    ``GET /rooms/{roomId}/context/{eventId}``, as well as correcting the
-    example for that API
-  - Clarify the behaviour of the "Room History Visibility" module; in
-    particular, the behaviour of the ``shared`` history visibilty, and how
-    events at visibility boundaries should be handled
-  - Separate the "Room Previews" module from "Guest access"
-  - Reword the description of the ``profile_tag`` property in
-    ``PUT /pushers/set``, and note that it is not mandatory.
-
-
-.. [#] Our `versioning policy <../index.html#specification-versions>`_ would
-   strictly require that a breaking change be denoted by a new major
-   specification version. However we are not aware of any clients which
-   rely on the old behaviour here, nor server implementations which offer
-   it, so we have chosen to retain the r0 designation on this occasion.
-
-r0.0.1
-======
-
-This release includes the following changes since r0.0.0:
-
-- API changes:
-  - Added new ``/versions`` API
-  - ``/createRoom`` takes an optional ``invite_3pid`` parameter
-  - ``/publicRooms`` returns an ``avatar_url`` result
-- The following APIs are now deprecated:
-  - ``/initialSync``
-  - ``/events``
-  - ``/events/:eventId``
-  - ``/rooms/:roomId/initialSync``
-- Spec clarifications
-  - Document inter-version compatibility
-  - Document the parameters to the ``/user/:userId/filter`` API
-  - Document the ``next_batch`` parameter on ``/search``
-  - Document the membership states on ``m.room.member`` events
-  - Minor clarifications/corrections to:
-    - Guest access module
-    - Search module
-    - ``/login`` API
-    - ``/rooms/:roomId/send/:eventType/:txnId`` API
-    - ``/rooms/:roomId/context/:eventId`` API
-
-r0.0.0
-======
-
-This is the first release of the client-server specification. It is largely a dump of what has currently been implemented, and there are several inconsistencies.
-
-An upcoming minor release will deprecate many of these inconsistencies, and they will be removed in the next major release.
-
-Since the draft stage, the following major changes have been made:
-- /api/v1 and /v2_alpha path segments have been replaced with the major version of the release (i.e. 'r0').
-- Some POST versions of APIs with both POST and PUT have been removed.
-- The specification has been split into one specification per API. This is the client-server API. The server-server API can be found documented separately.
-- All APIs are now documented using Swagger
-- The following modules have been added:
-  - Content repository
-  - Instant messaging
-  - Push notification
-  - History visibility
-  - Search
-  - Invites based on third party identifiers
-  - Room tagging
-  - Guest access
-  - Client config
-- The following APIs were added:
-  - ``/sync``
-  - ``/publicRooms``
-  - ``/rooms/{roomId}/forget``
-  - ``/admin/whois``
-  - ``/rooms/{roomId}/redact``
-  - ``/user/{userId}/filter``
-- The following APIs have been significantly modified:
-  - Invitations now contain partial room state
-  - Invitations can now be rejected
-  - ``/directory``
-- The following events have been added:
-  - ``m.room.avatar``
-- Example signed json is included for reference
-- Commentary on display name calculation was added

drafts/ancient_federated_versioning_design_notes.rst

@@ -1,11 +0,0 @@
-Versioning is, like, hard for backfilling backwards because of the number of homeservers involved.
-
-The way we solve this is by doing versioning as an acyclic directed graph of PDUs. For backfilling purposes, this is done on a per context basis.
-When we send a PDU we include all PDUs that have been received for that context that hasn't been subsequently listed in a later PDU. The trivial case is a simple list of PDUs, e.g. A <- B <- C. However, if two servers send out a PDU at the same to, both B and C would point at A - a later PDU would then list both B and C.
-
-Problems with opaque version strings:
-    - How do you do clustering without mandating that a cluster can only have one transaction in flight to a given remote homeserver at a time.
-      If you have multiple transactions sent at once, then you might drop one transaction, receive another with a version that is later than the dropped transaction and which point ARGH WE LOST A TRANSACTION.
-    - How do you do backfilling? A version string defines a point in a stream w.r.t. a single homeserver, not a point in the context.
-
-We only need to store the ends of the directed graph, we DO NOT need to do the whole one table of nodes and one of edges.

drafts/application_services.rst

@@ -1,244 +0,0 @@
-.. TODO
-  Sometimes application services need to create rooms (e.g. when lazy loading 
-  from room aliases). Created rooms need to have a user that created them, so 
-  federation works (as it relies on an entry existing in m.room.member). We should 
-  be able to add metadata to m.room.member to state that this user is an application 
-  service, a virtual user, etc.
-
-Application Services
-====================
-
-Overview
-========
-
-Application services provide a way of implementing custom serverside functionality
-on top of Matrix without the complexity of implementing the full federation API.
-By acting as a trusted service logically located behind an existing homeserver,
-Application services are decoupled from:
-
-* Signing or validating federated traffic or conversation history
-* Validating authorisation constraints on federated traffic
-* Managing routing or retry schemes to the rest of the Matrix federation
-
-As such, developers can focus entirely on implementing application logic rather
-than being concerned with the details of managing Matrix federation.
-
-Features available to application services include:
-
-* Privileged subscription to any events available to the homeserver
-* Synthesising virtual users
-* Synthesising virtual rooms
-* Injecting message history for virtual rooms
- 
-Features not provided by application services include:
-
-* Intercepting and filtering/modifying message or behaviour within a room
-  (this is a job for a Policy Server, as it requires a single logical focal
-  point for messages in order to consistently apply the custom business logic)
- 
-Example use cases for application services include:
-
-* Exposing existing communication services in Matrix
-
-  * Gateways to/from standards-based protocols (SIP, XMPP, IRC, RCS (MSRP), SIMPLE, Lync, etc)
-  * Gateways to/from closed services (e.g. WhatsApp)
-  * Gateways could be architected as:
-  
-    * Act as a virtual client on the non-Matrix network
-      (e.g. connect as multiple virtual clients to an IRC or XMPP server)
-    * Act as a server on the non-Matrix network
-      (e.g. speak s2s XMPP federation, or IRC link protocol)
-    * Act as an application service on the non-Matrix network
-      (e.g. link up as IRC services, or an XMPP component)
-    * Exposing a non-Matrix client interface listener from the AS
-      (e.g. listen on port 6667 for IRC clients, or port 5222 for XMPP clients)
-
-
-* Bridging existing APIs into Matrix
-   * e.g. SMS/MMS aggregator APIs
-   * Domain-specific APIs such as SABRE
-
-* Integrating more exotic content into Matrix
-   * e.g. MIDI<->Matrix gateway/bridge
-   * 3D world <-> Matrix bridge
-
-* Application services:
-   * Search engines (e.g. elasticsearch search indices)
-   * Notification systems (e.g. send custom pushes for various hooks)
-   * VoIP Conference services
-   * Text-to-speech and Speech-to-text services
-   * Signal processing
-   * IVR
-   * Server-machine translation
-   * Censorship service
-   * Multi-User Gaming (Dungeons etc)
-   * Other "constrained worlds" (e.g. 3D geometry representations)
-
-     * applying physics to a 3D world on the serverside
-
-       * (applying gravity and friction and air resistance... collision detection)
-       * domain-specific merge conflict resolution of events
-
-   * Payment style transactional usecases with transactional guarantees
-
-Architecture Outline
-====================
-
-The application service registers with its host homeserver to offer its services.
-
-In the registration process, the AS provides:
-
-* Credentials to identify itself as an approved application service for that HS
-* Details of the namespaces of users and rooms the AS is acting on behalf of and
-  "subscribing to"
-* Namespaces are defined as a list of regexps against which to match room aliases,
-  room IDs, and user IDs. Regexps give the flexibility to say, sub-domain MSISDN
-  ranges per AS, whereas a blunt prefix string does not. These namespaces are further
-  configured by setting whether they are ``exclusive`` or not. An exclusive namespace
-  prevents entities other than the aforementioned AS from creating/editing/deleting
-  entries within that namespace. This does not affect the visibility/readability of
-  entries within that namespace (e.g. it doesn't prevent users joining exclusive
-  aliases, or ASes from listening to exclusive aliases, but does prevent both users
-  and ASes from creating/editing/deleting aliases within that namespace).
-* There is overlap between selecting events via the csv2 Filter API and subscribing
-  to events here - perhaps subscription involves passing a filter token into the
-  registration API.
-* A URL base for receiving requests from the HS (as the AS is a server,
-  implementers expect to receive data via inbound requests rather than
-  long-poll outbound requests)
-
-On HS handling events to unknown users:
-
-* If the HS receives an event for an unknown user who is in the namespace delegated to 
-  the AS, then the HS queries the AS for the profile of that user.  If the AS
-  confirms the existence of that user (from its perspective), then the HS
-  creates an account to represent the virtual user.
-* The namespace of virtual user accounts should conform to a structure like
-  ``@.irc.freenode.Arathorn:matrix.org``.  This lets Matrix users communicate with
-  foreign users who are not yet mapped into Matrix via 3PID mappings or through
-  an existing non-virtual Matrix user by trying to talk to them via a gateway.
-* The AS can alternatively preprovision virtual users using the existing CS API
-  rather than lazy-loading them in this manner.
-* The AS may want to link the matrix ID of the sender through to their 3PID in
-  the remote ecosystem.  E.g. a message sent from ``@matthew:matrix.org`` may wish
-  to originate from Arathorn on irc.freenode.net in the case of an IRC bridge.
-  It's left as an AS implementation detail as to how the user should authorise
-  the AS to act on its behalf.
-
-On HS handling events to unknown rooms:
-
-* If the HS receives an invite to an unknown room which is in the namespace
-  delegated to the AS, then the HS queries the AS for the existence of that room.
-  If the AS confirms its existence (from its perspective), then the HS creates
-  the room.
-* The initial state of the room may be populated by the AS by querying an
-  initialSync API (probably a subset of the CS initialSync API, to reuse the
-  same pattern for the equivalent function).  As messages have to be signed
-  from the point of ``m.room.create``, we will not be able to back-populate
-  arbitrary history for rooms which are lazy-created in this manner, and instead
-  have to chose the amount of history to be synchronised into the AS as a one-off.
-* If exposing arbitrary history is required, then:
-   
-  * either: the room history must be preemptively provisioned in the HS by the AS via
-    the CS API (TODO: meaning the CS API needs to support massaged
-    timestamps), resulting in conversation history being replicated between
-    the HS and the source store.
-  * or: the HS must delegate conversation storage entirely to the
-    AS using a Storage API (not defined here) which allows the existing
-    conversation store to back the HS, complete with all necessary Matrix
-    metadata (e.g. hashes, signatures, federation DAG, etc).  This obviously
-    increases the burden of implementing an AS considerably, but is the only
-    option if the implementer wants to avoid duplicating conversation history
-    between the external data source and the HS.
-
-On HS handling events to existing users and rooms:
-
-* If the HS receives an event for a user or room that already exists (either
-  provisioned by the AS or by normal client interactions), then the message
-  is handled as normal.
-* Events in the namespaces of rooms and users that the AS has subscribed to
-  are pushed to the AS using the same pattern as the federation API (without
-  any of the encryption or federation metadata).  This serves precisely the
-  same purpose as the CS event stream and has the same data flow semantics
-  (and indeed an AS implementer could chose to use the CS event stream instead)
-  
-  * Events are linearised to avoid the AS having to handle the complexity of
-    linearisation, and because if linearisation is good enough for CS, it
-    should be good enough for AS. Should the AS require non-linearised events
-    from Matrix, it should implement the federation API rather than the AS API
-    instead.
-  * HS->AS event pushes are retried for reliability with sequence numbers
-    (or logical timestamping?) to preserve the linearisation order and ensure
-    a reliable event stream.
-  * Clustered HSes must linearise just as they do for the CS API.  Clustered
-    ASes must loadbalance the inbound stream across the cluster as required.
-
-On AS relaying events from unknown-to-HS users:
-
-* AS injects the event to the HS using the CS API, irrespective of whether the
-  target user or room is known to the HS or not.  If the HS doesn't recognise
-  the target it goes through the same lazy-load provisioning as per above.
-* The reason for not using a subset of the federation API here is because it
-  allows AS developers to reuse existing CS SDKs and benefit from the more
-  meaningful error handling of the CS API.  The sending user ID must be
-  explicitly specified, as it cannot be inferred from the access_token, which
-  will be the same for all AS requests.
-
-  * TODO: or do we maintain a separate ``access_token`` mapping?  It seems like
-    unnecessary overhead for the AS developer; easier to just use a single
-    privileged ``access_token`` and just track which ``user_id`` is emitting events?
-  * If the AS is spoofing the identity of a real (not virtual) matrix user,
-    we should actually let them log themselves in via OAuth2 to give permission
-    to the AS to act on their behalf.
-  * We can't auth gatewayed virtual users from 3rd party systems who are being
-    relayed into Matrix, as the relaying is happening whether the user likes it
-    or not.  Therefore we do need to be able to spoof sender ID for virtual users.
- 
-On AS relaying events in unknown-to-HS rooms:
-
-* See above.
-
-On AS publishing aliases for virtual rooms:
-
-* AS uses the normal alias management API to preemptively create/delete public
-  directory entries for aliases for virtual rooms provided by the AS.
-* In order to create these aliases, the underlying room ID must also exist, so
-  at least the ``m.room.create`` of that room must also be prepopulated.  It seems
-  sensible to prepopulate the required initial state and history of the room to
-  avoid a two-phase prepopulation process.
-   
-On unregistering the AS from the HS:
-
-* An AS must tell the HS when it is going offline in order to stop receiving
-  requests from the HS.  It does this by hitting an API on the HS.
-
-AS Visibility:
-
-* If an AS needs to sniff events in a room in order to operate on them (e.g.
-  to act as a search engine) but not inject traffic into the room, it should
-  do so by subscribing to the relevant events without actually joining the room.
-* If the AS needs to participate in the room as a virtual user (e.g. an IVR
-  service, or a bot, or a gatewayed virtual user), it should join the room
-  normally.
-* There are rare instances where an AS may wish to participate in a room
-  (including inserting messages), but be hidden from the room list - e.g. a
-  conferencing server focus bot may wish to join many rooms as the focus and
-  both listen to VoIP setups and inject its own VoIP answers, without ever
-  being physically seen in the room.  In this scenario, the user should set
-  its presence to 'invisible', a state that HSes should only allow AS-authed
-  users to set.
-   
-E2E Encryption
-
-* The AS obviously has no visibility to E2E encrypted messages, unless it is
-  explicitly added to an encrypted room and participates in the group chat
-  itself.
-
-Extensions to CS API
-====================
-
-* Ability to assert the identity of the virtual user for all methods.
-* Ability to massage timestamps when prepopulating historical state and
-  messages of virtual rooms (either by overriding ``origin_server_ts`` (preferred) or
-  adding an ``as_ts`` which we expect clients to honour)
-* Ability to delete aliases (including from the directory) as well as create them.

drafts/data_flows.rst

@@ -1,222 +0,0 @@
-Data flows for use cases
-========================
-
-::
-
- <- Data from server to client
- -> Data from client to server
-
-Instant Messaging
------------------
-
-Without storage
-~~~~~~~~~~~~~~~
-
-::
-
- Home screen
-   Data required on load:
-    <- For each room the user is joined: Name, topic, # members, last message, room ID, aliases
-   Data required when new message arrives for a room:
-    <- Room ID, message content, sender (user ID, display name, avatar url)
-   Data required when someone invites you to a room:
-    <- Room ID, sender (user ID, display name, avatar url), Room Name, Room Topic
-   Data required when you leave a room on another device:
-    <- Room ID
-   Data required when you join a room on another device:
-    <- Name, topic, # members, last message, room ID, aliases
-   Data required when your profile info changes on another device:
-    <- new profile info e.g. avatar, display name, etc.
-    
-   Creating a room
-    -> Invitee list of user IDs, public/private, name of room, alias of room, topic of room
-    <- Room ID
-   
-   Joining a room (and dumped into chat screen on success)
-    -> Room ID / Room alias
-    <- Room ID, Room aliases (plural), Name, topic, member list (f.e. member: user ID, 
-       avatar, presence, display name, power level, whether they are typing), enough 
-       messages to fill screen (and whether there are more)
-      
- Chat Screen
-   Data required when member name changes:
-    <- new name, room ID, user ID, when in the context of the room did this occur
-   Data required when the room name changes:
-    <- new name, room ID, old room name?
-   Invite a user:
-    -> user ID, room ID
-    <- display name / avatar of user invited (if known)
-   Kick a user:
-    -> user ID, room ID
-    <- what message it came after
-   Leave a room:
-    -> room ID
-    <- what message it came after
-      
-   Send a message
-    -> Message content, room ID, message sequencing (eg sending my 1st, 2nd, 3rd msg)
-    <- actual content sent (if server mods it), what message it comes after (to correctly
-       display the local echo)
-      
-    Place a call (receive a call is just reverse)
-     <- turn servers
-     -> SDP offer
-     -> Ice candidates (1 by 1; trickling)
-     <- SDP answer
-     <- Ice candidates
-    
-    Scrolling back (infinite scrolling)
-     -> Identifier for the earliest message, # requested messages
-     <- requested messages (f.e change in display name, what the old name was), whether
-        there are more.
-
-
-With storage
-~~~~~~~~~~~~
-::
-    
-  Home Screen
-    On Load
-     -> Identifier which tells the server the client's current state (which rooms it is aware
-        of, which messages it has, what display names for users, etc..)
-     <- A delta from the client's current state to the current state on the server (e.g. the
-        new rooms, the *latest* message if different, the changed display names, the new 
-        invites, etc). f.e Room: Whether the cache of the room that you have has been replaced 
-        with this new state.
-        
-    Pre-load optimisation (not essential for this screen)
-      -> Number of desired messages f.e room to cache
-      <- f.e Room: the delta OR the entire state
-     
-
-Bug Tracking
-------------
-::
-
-  Landing Page
-    On Load
-     <- Issues assigned to me, Issues I'm watching, Recent activity on other issues includes
-        comments, list of projects
-    
-    Search for an issue (assume text)
-     -> Search string
-     <- List of paginated issues
-       Request page 2:
-        -> Page number requested
-        <- Page of paginated issues
-  
-  Issue Page
-    On Load
-     -> Issue ID and Project ID (equiv to Room)
-     <- Issue contents e.g. priority, resolution state, etc. All comments e.g. user ID, 
-        comment text, timestamp. Entire issue history e.g. changes in priority
-     
-    Post a comment
-     -> Issue ID, comment content, Project ID (equiv to Room)
-     <- actual content sent (if modded), what comment it comes after
-    
-    Set issue priority
-     -> Issue ID, Project ID, desired priority
-     <- What action in the history it came after
-     
-    Someone else sets issue priority
-     <- Issue ID, Project ID, new priority, where in the history
-
-
-Mapping model use cases to matrix models (Room, Message, etc)
-=============================================================
-
-To think about:
- - Do we want to support the idea of forking off new rooms from existing ones? This
-   and forums could benefit from it.
-
-Bug tracking UI
----------------
-::
-
- Projects => Rooms
- Issues => Message Events
- Comments => Message Events (relates_to key)
-
-Projects:
- - Unlikely that there will be 100,000s of issues, so having to pull in all the issues for a project is okay.
- - Permissions are usually per project and this Just Works.
- - New issues come in automatically and Just Work.
- - Can have read-only members
-
-Issues:
- - Don't really want 1 Room per Issue, else you can have thousands of Rooms PER PROJECT, hence choice for    
-   Issues as Messages. Don't need to join a room for each issue.
- - Idea of issue owner is clear (sender of the message)
- - Updating issues requires an additional event similar to comments (with ``relates_to``)? Could possibly
-   be state events? Don't really want all the history if say the priority was changed 1000 times, just want
-   the current state of the key.
-
-Comments:
- - Additional event with ``relates_to`` key.
-
-
-Forum
------
-::
-
- Forum => Room (with pointers to Board Rooms)
- Boards => Room (with pointers to Thread Rooms)
- Threads => Room
- Messages => Message Events
-
-Forum:
- - Contains 10s of Boards.
- - Contains special Message Events which point to different rooms f.e Board.
-
-Boards:
- - Contains 100s of Threads.
- - Contains special Message Events which point to different rooms f.e. Thread.
-
-Threads:
- - Contains 100s of Messages.
-
-Can't do this nicely with the current Federation API because you have loads of
-Rooms and what does posting a message look like? Creating a thread is done by..?
-The user who is posting cannot create the thread because otherwise they would be
-the room creator and have ultimate privileges. So it has to be created by a bot
-of some kind which ties into auth (Application services?). To follow a board,
-you need a bot to join the Board Room and then watch it for changes... 
-
-Fundamental problem with forums is that there is only 1 PDU graph per room and
-you either have to pull in lots of graphs separately or one graph and filter it
-separately to get to the desired sub set of data. You have to subscribe into a
-lot of graphs if you subscribe to a board... If you have the entire board...
-good luck scrollbacking a particular thread.
-
-
-Google+ Community
------------------
-::
-
- Community => Room (with pointers to Category Rooms)
- Category => Room
- Post => Message Events
- Comment => Message Events (relates_to key)
-
-Community:
- - Contains 10s of categories.
- - Contains special Message Events which point to different rooms f.e Category.
- - Moderators of the community are mods in this room. They are in charge of making
-   new categories and the subsequent rooms. Can get a bit funky if a mod creates a
-   category room without the same permissions as the community room... but another
-   mod can always delete the pointer to the buggy category room and make a new one.
- - Do we want to support the idea of forking off new rooms from existing ones? This
-   and forums could benefit from it.
-
-Category:
- - Contains 1000s of posts.
- - Same permissions as the community room. How to enforce? Fork off the community
-   room?
-
-Posts:
- - Contains 10s of comments.
-
-This is similar to forums but you can more reasonably say "screw it, pull in the
-entire community of posts."
-

drafts/erik-model.rst

@@ -1,141 +0,0 @@
-This is a standalone description of the data architecture of Synapse. There is a
-lot of overlap with the current specification, so it has been split out here for
-posterity. Hopefully all the important bits have been merged into the relevant
-places in the main spec.
-
-
-Model
------
-
-Overview
-~~~~~~~~
-
-Matrix is used to reliably distribute data between sets of `users`.
-
-Users are associated with one of many matrix `servers`. These distribute,
-receive and store data on behalf of its registered users. Servers can be run on
-any host accessible from the internet.
-
-When a user wishes to send data to users on different servers the local server
-will distribute the data to each remote server. These will in turn distribute
-to their local users involved.
-
-A user sends and receives data using one or more authenticated `clients`
-connected to his server. Clients may persist data locally or request it when
-required from the server.
-
-Events
-~~~~~~
-An event is a collection of data (the `payload`) and metadata to be distributed
-across servers and is the primary data unit in Matrix.  Events are extensible
-so that clients and servers can add extra arbitrary fields to both the payload
-or metadata.
-
-Events are distributed to interested servers upon creation. Historical events
-may be requested from servers; servers are not required to produce all
-or any events requested.
-
-All events have a metadata `type` field that is used by client and servers to
-determine how the payload should be processed and used. There are a number of
-types reserved by the protocol for particular uses, but otherwise types may be
-defined by applications, clients or servers for their own purposes.
-
-.. TODO : Namespacing of new types.
-
-Graph
-+++++
-Each event has a list of zero or more `parent` events. These relations form
-directed acyclic graphs of events called `event graphs`. Every event graph has
-a single root event, and each event graph forms the basis of the history of a
-matrix room.
-
-Event graphs give a partial ordering of events, i.e. given two events one may
-be considered to have come before the other if one is an ancestor of the other.
-Since two events may be on separate branches, not all events can be compared in
-this manner.
-
-Every event has a metadata `depth` field that is a positive integer that is
-strictly greater than the depths of any of its parents. The root event should
-have a depth of 1.
-
-[Note: if one event is before another, then it must have a strictly smaller
-depth]
-
-Integrity
-+++++++++
-
-.. TODO: Specify the precise subset of essential fields
-
-Portions of events will be signed by one or more servers or clients. The parent
-relations, type, depth and payload (as well as other metadata fields that will
-be specified) must be signed by the originating server. [Note: Thus, once an
-event is distributed and referenced by later events, they effectively become
-immutable].
-
-The payload may also be encrypted by clients, except in the case where the
-payload needs to be interpreted by the servers. A list of event types that
-cannot have an encrypted payload are given later.
-
-
-State
-~~~~~
-Event graphs may have meta information associated with them, called `state`.
-State can be updated over time by servers or clients, subject to
-authorisation.
-
-The state of a graph is split into `sections` that can be atomically updated
-independently of each other.
-
-State is stored within the graph itself, and can be computed by looking at the
-graph in its entirety. We define the state at a given event to be the state of
-the sub graph of all events "before" and including that event.
-
-Some sections of the state may determine behaviour of the protocol, including
-authorisation and distribution. These sections must not be encrypted.
-
-State Events
-++++++++++++
-`State events` are events that update a section of state data for a room. These
-state events hold all the same properties of events, and are part of the event
-graph. The payload of the event is the replacement value for the particular
-section of state being updated.
-
-State events must also include a `state_key` metadata field. The pair of fields
-type and state_key uniquely defines the section of state that is to be updated.
-
-State Resolution
-++++++++++++++++
-A given state section may have multiple state events associated with it in a
-given graph. A consistent method of selecting which state event takes
-precedence is therefore required.
-
-This is done by taking the latest state events, i.e. the set of events that are
-either incomparable or after every other event in the graph. A state resolution
-algorithm is then applied to this set to select the single event that takes
-precedence.
-
-The state resolution algorithm must be transitive and not depend on server
-state, as it must consistently select the same event irrespective of the server
-or the order the events were received in.
-
-State Dictionary
-++++++++++++++++
-The state dictionary is the mapping from sections of state to the state events
-which set the section to its current value.  The state dictionary, like the
-state itself, depends on the events currently in the graph and so is updated
-with each new event received.
-
-Since the sections of the state are defined by the pair of strings from the
-type and state_key of the events that update them, the state dictionary can be
-defined as a mapping from the pair (type, state_key) to a state event with
-those values in the graph.
-
-Deleting State
-++++++++++++++
-State sections may also be deleted, i.e. removed from the state dictionary. The
-state events will still be present in the event graph.
-
-This is done by sending a special state event indicating that the given entry
-should be removed from the dictionary. These events follow the same rules for
-state resolution, with the added requirement that it loses all conflicts.
-[Note: This is required to make the algorithm transitive.]

drafts/erikj_federation.rst

@@ -1,408 +0,0 @@
-Federation
-==========
-.. sectnum::
-.. contents:: Table of Contents
-
-Authorization
--------------
-
-When receiving new events from remote servers, or creating new events, a server 
-must know whether that event is allowed by the authorization rules. These rules
-depend solely on the state at that event. The types of state events that affect
-authorization are:
-
-- ``m.room.create``
-- ``m.room.member``
-- ``m.room.join_rules``
-- ``m.room.power_levels``
-
-Servers should not create new events that reference unauthorized events. 
-However, any event that does reference an unauthorized event is not itself
-automatically considered unauthorized. 
-
-Unauthorized events that appear in the event graph do *not* have any effect on 
-the state of the graph. 
-
-.. Note:: This is in contrast to redacted events which can still affect the 
-          state of the graph. For example, a redacted *"join"* event will still
-          result in the user being considered joined.
-          
-
-Rules
-~~~~~
-
-The following are the rules to determine if an event is authorized (this does
-include validation).
-
-**TODO**: What signatures do we expect?
-
-1. If type is ``m.room.create`` allow if and only if it has no prev events.
-#. If type is ``m.room.member``:
-  
-   a. If ``membership`` is ``join``:
-    
-      i. If the previous event is an ``m.room.create``, the depth is 1 and 
-         the ``state_key`` is the creator, then allow.
-      #. If the ``state_key`` does not match ``sender`` key, reject.
-      #. If the current state has ``membership`` set to ``join``.
-      #. If the ``sender`` is in the ``m.room.may_join`` list. [Not currently 
-         implemented]
-      #. If the ``join_rules`` is:
-      
-         - ``public``:  allow.
-         - ``invite``: allow if the current state has ``membership`` set to 
-           ``invite``
-         - ``knock``: **TODO**.
-         - ``private``: Reject.
-         
-      #. Reject
-
-   #. If ``membership`` is ``invite`` then allow if ``sender`` is in room, 
-      otherwise reject.
-   #. If ``membership`` is ``leave``:
-   
-      i. If ``sender`` matches ``state_key`` allow.
-      #. If ``sender``'s power level is greater than the the ``kick_level``
-         given in the current ``m.room.power_levels`` state (defaults to 50),
-         and the ``state_key``'s power level is less than or equal to the
-         ``sender``'s power level, then allow.
-      #. Reject.
-      
-   #. If ``membership`` is ``ban``:
-   
-      i. **TODO**.
-   
-   #. Reject.
-
-#. Reject the event if the event type's required power level is less that the
-   ``sender``'s power level.
-#. If the ``sender`` is not in the room, reject.
-#. If the type is ``m.room.power_levels``:
-
-   a. **TODO**.
-
-#. Allow.
-
-
-Definitions
-~~~~~~~~~~~
-
-Required Power Level
-  A given event type has an associated *required power level*. This is given
-  by the current ``m.room.power_levels`` event, it is either listed explicitly
-  in the ``events`` section or given by either ``state_default`` or 
-  ``events_default`` depending on if the event type is a state event or not.
-
-
-Auth events
-~~~~~~~~~~~
-
-The auth events of an event are the set of events used by the authorization 
-algorithm to accept the event. These should be a subset of the current state.
-
-A server is required to store the complete chain of auth events for all events
-it serves to remote servers.
-
-All auth events have type:
-
- - ``m.room.create``
- - ``m.room.power_levels``
- - ``m.room.member``
-
-.. todo
-    We probably should probably give a lower band of how long auth events
-    should be kept around for.
-
-Auth chain
-~~~~~~~~~~
-
-The *auth chain* for an event is the recursive list of auth events and the auth
-chain for those auth events.
-
-.. Note:: The auth chain for an event gives all the information a server needs
-          to accept an event. However, being given an auth chain for an event
-          that appears valid does not mean that the event might not later be
-          rejected. For example if we discover that the sender had been banned
-          between the join event listed in the auth events and the event being
-          authed.
-
-**TODO**: Clean the above explanations up a bit.
-
-
-Auth chain resolution
-~~~~~~~~~~~~~~~~~~~~~
-
-If an auth check fails, or if we get told something we accepted should have
-been rejected, we need to try and determine who is right.
-
-If two servers disagree about the validity of the auth events, both should
-inform the other of what they think the current auth chain is. If either are
-missing auth events that they know are valid (through authorization and state
-resolution) they process the missing events as usual.
-
-If either side notice that the other has accepted an auth events we think
-should be rejected (for reasons *not* in their auth chain), that server should
-inform the other with suitable proof.
-
-The proofs can be:
-
-- An *event chain* that shows an auth event is *not* an ancestor of the event.
-  This can be done by giving the full ancestor chains up to the depth of the
-  invalid auth event.
-- Given an event (and event chain?) showing that authorization had been revoked.
-
-If a server discovers it cannot prove the other side is wrong, then it accepts
-that the other is correct; i.e. we always accept that the other side is correct
-unless we can prove otherwise.
-
-
-
-State Resolution
-----------------
-
-    **TODO**
-
-When two branches in the event graph merge, the state of those branches might
-differ, so a *state resolution* algorithm must be used to determine the current
-state of the resultant merge.
-
-The properties of the state resolution algorithm are:
-
-- Must only depend on the event graph, and not local server state.
-- When two state events are comparable, the descendant one should be picked.
-- Must not require the full event graph.
-
-The following algorithm satisfies these requirements; given two or more events,
-pick the one with the greatest:
-
-#. Depth.
-#. Hash of event_id.
-
-
-This works except in the case of auth events, where we need to mitigate against
-the attack where servers artificially netsplit to avoid bans or power level
-changes.
-
-We want the following rules to apply:
-
-#. If power levels have been changed on two different branches use the rules
-   above, ensuring that the one picked is a valid change from the one not picked.
-#. Similarly handle membership changes (e.g. bans, kicks, etc.)
-#. Any state merged must be allowed by the newly merged auth events. If none of
-   the candidate events for a given state are allowed, we pick the last event
-   given by the ordering above (i.e. we pick one with the least depth).
-
-
-
-State Conflict Resolution
--------------------------
-
-If a server discovers that it disagrees with another about the current state,
-it can follow the same process outlined in *Auth chain resolution* to resolve
-these conflicts.
-
-Constructing a new event
-------------------------
-
-    **TODO**
-
-When constructing a new event, the server should insert the following fields:
-
-- ``prev_events``: The list of event ids of what the server believes are the
-  current leaf nodes of the event graph (i.e., nodes that have been received
-  but are yet to be referenced by another event).
-- ``depth``: An integer one greater than the maximum depth of the event's
-  previous events.
-- ``auth_events``: The list of event ids that authorizes this event. This
-  should be a subset of the current state.
-- ``origin_server_ts``: The time the server created the event.
-- ``origin``: The name of the server.
-
-
-Signing and Hashes
-~~~~~~~~~~~~~~~~~~
-
-    **TODO**
-
-Validation
-----------
-
-    **TODO**
-
-Domain specific string
-    A string of the form ``<prefix><localpart>:<domain>``, where <prefix> is a
-    single character, ``<localpart>`` is an arbitrary string that does not
-    include a colon, and `<domain>` is a valid server name.
-
-``room_id``
-    A domain specific string with prefix ``!`` that is static across all events
-    in a graph and uniquely identifies it. The ``domain`` should be that of the
-    homeserver that created the room (i.e., the server that generated the
-    first ``m.room.create`` event).
-
-``sender``
-    The entity that logically sent the event. This is usually a user id, but
-    can also be a server name.
-
-User Id
-    A domain specific string with prefix ``@`` representing a user account. The
-    ``domain`` is the homeserver of the user and is the server used to contact
-    the user.
-
-Joining a room
---------------
-
-If a user requests to join a room that the server is already in (i.e. the a
-user on that server has already joined the room) then the server can simply
-generate a join event and send it as normal.
-
-If the server is not already in the room it needs to will need to join via
-another server that is already in the room. This is done as a two step process.
-
-First, the local server requests from the remote server a skeleton of a join
-event. The remote does this as the local server does not have the event graph
-to use to fill out the ``prev_events`` key in the new event. Critically, the
-remote server does not process the event it responded with.
-
-Once the local server has this event, it fills it out with any extra data and
-signs it. Once ready the local server sends this event to a remote server
-(which could be the same or different from the first remote server), this
-remote server then processes the event and distributes to all the other
-participating servers in that room. The local server is told about the
-current state and complete auth chain for the join event. The local server
-can then process the join event itself.
-
-
-.. Note::
-   Finding which server to use to join any particular room is not specified.
-
-
-Inviting a user
----------------
-
-To invite a remote user to a room we need their homeserver to sign the invite
-event. This is done by sending the event to the remote server, which then signs
-the event, before distributing the invite to other servers.
-
-
-Handling incoming events
-------------------------
-
-When a server receives an event, it should:
-
-#. Check if it knows about the room. If it doesn't, then it should get the
-   current state and auth events to determine whether the server *should* be in
-   the room. If so continue, if not drop or reject the event
-#. If the server already knew about the room, check the prev events to see if
-   it is missing any events. If it is, request them. Servers should limit how
-   far back they will walk the event graph for missing events.
-#. If the server does not have all the prev events, then it should request the
-   current state and auth events from a server.
-
-
-Failures
---------
-
-A server can notify a remote server about something it thinks it has done
-wrong using the failures mechanism. For example, the remote accepted an event
-the local think it shouldn't have.
-
-A failure has a severity level depending on the action taken by the local
-server. These levels are:
-
-``FATAL``
-    The local server could not parse the event, for example due to a missing
-    required field.
-
-``ERROR``
-    The local server *could* parse the event, but it was rejected. For example,
-    the event may have failed an authorization check.
-
-``WARN``
-    The local server accepted the event, but something was unexpected about it.
-    For example, the event may have referenced another event the local server
-    thought should be rejected.
-
-A failure also includes several other fields:
-
-``code``
-    A numeric code (to be defined later) indicating a particular type of
-    failure.
-
-``reason``
-    A short string indicating what was wrong, for diagnosis purposes on the
-    remote server.
-
-``affected``
-    The event id of the event this failure is responding to. For example, if
-    an accepted event referenced a rejected event, this would point to the
-    accepted one.
-
-``source``
-    The event id of the event that was the source of this unexpected behaviour.
-    For example, if an accepted event referenced a rejected event, this would
-    point to the rejected one.
-
-
-Appendix
-========
-
-    **TODO**
-
-Example event:
-
-.. code::
-
-    {
-        "auth_events": [
-            [
-                "$14187571482fLeia:localhost:8480",
-                {
-                    "sha256": "kiZUclzzPetHfy0rVoYKnYXnIv5VxH8a4996zVl8xbw"
-                }
-            ],
-            [
-                "$14187571480odWTd:localhost:8480",
-                {
-                    "sha256": "GqtndjviW9yPGaZ6EJfzuqVCRg5Lhoyo4YYv1NFP7fw"
-                }
-            ],
-            [
-                "$14205549830rrMar:localhost:8480",
-                {
-                    "sha256": "gZmL23QdWjNOmghEZU6YjqgHHrf2fxarKO2z5ZTbkig"
-                }
-            ]
-        ],
-        "content": {
-            "body": "Test!",
-            "msgtype": "m.text"
-        },
-        "depth": 250,
-        "event_id": "$14207181140uTFlx:localhost:8480",
-        "hashes": {
-            "sha256": "k1nuafFdFvZXzhb5NeTE0Q2Jkqu3E8zkh3uH3mqwIxc"
-        },
-        "origin": "localhost:8480",
-        "origin_server_ts": 1420718114694,
-        "prev_events": [
-            [
-                "$142071809077XNNkP:localhost:8480",
-                {
-                    "sha256": "xOnU1b+4LOVz5qih0dkNFrdMgUcf35fKx9sdl/gqhjY"
-                }
-            ]
-        ],
-        "room_id": "!dwZDafgDEFTtpPKpLy:localhost:8480",
-        "sender": "@bob:localhost:8480",
-        "signatures": {
-            "localhost:8480": {
-                "ed25519:auto": "Nzd3D+emFBJJ4LCTzQEZaKO0Sa3sSTR1fGpu8OWXYn+7XUqke9Q1jYUewrEfxb3lPxlYWm/GztVUJizLz1K5Aw"
-            }
-        },
-        "type": "m.room.message",
-        "unsigned": {
-            "age": 500
-        }
-    }
-

drafts/flows_and_auth.rst

@@ -1,146 +0,0 @@
-Failures
---------
-
-A server may encouter an error when trying to process an event received from a
-remote server. In these cases the server may send a `failure` to the remote.
-
-A `failure` references both the event that it was trying to process and the
-event that triggered the processing. For example, a failure may be emitted if
-one of the parents of the received events was not authorized.
-
-A failure also includes a `severity` field that indicates what action was taken
-by the server. There are three valid values:
-
-  * `Fatal`: The server failed to parse the event. The event is dropped by the
-    server as well as all descendants.
-  * `Error`: The server rejected the event, for example due to authorization.
-    That event is dropped, but descendants may be accepted.
-  * `Warn`: The server accepted all events, but believes the remote did
-    something wrong. For example, references an event the local server believes
-    is unauthorized.
-
-
-Data Flows
-----------
-
-Invite
-++++++
-
-To invite a remote user to an existing room a server distributes an invitiation
-event signed by the remote invitee's server (allowing other servers in the room
-to be sure that the invitee's server had seen the invite.)
-
-To get the remote server's signature on the event it is sent in a special
-request to the remote server, which then responds with the signed invite (if it
-accepted it as valid.) The remote server may respond with an error if the user
-does not exist.
-
-Join
-++++
-
-If a server is already in the room it can simply emit a join event for the user
-joining.
-
-If the server is not currently in the room it needs to join via a remote server
-in the room, therefore to join a room a server must have have both the room id
-and a list of remote servers that may be in the room.
-
-To join via a remote server the local server first requests a valid join event
-for the room from the remote server. The local then fills it out, signs it, and
-then sends the final join event to the remote server for distribution. The
-remore responds to this second request with the current state of the room at
-the join request and the auth chain for that state.
-
-
-Authorization
--------------
-
-The authorization for an event depends solely on the current state at that
-event. If a policy server is configured for the room, then the authorization
-for the event is the signature of the policy server.
-
-The state events that affect whether an event is authorized are called
-`protocol events`, and are:
-
-  * `m.room.create`
-  * `m.room.power_levels`
-  * `m.room.member`
-  * `m.room.join_rules`
-
-All events *must* list all the protocol events that grant them their
-authorization. All origin servers *must* serve up on request the full graph of
-protocol events for all events it has sent. The graph of protocol events is the
-connected directed acyclic graph with events as nodes and the list of protocol
-events their edges.
-
-
-Join
-++++
-
-A user may join a room if:
-
-  * The join rule is "public".
-  * The join rule is "invite" and the user has been invited by a user that has
-    already joined.
-  * The user is in the `may_join` list.
-
-
-Invite
-++++++
-
-A user may invite another user if the join rule is either "public" or "invite"
-and the user has joined the room.
-
-
-Creation
-++++++++
-
-A `m.room.create` must be the first event in the room.
-
-
-Ban, Kick and Redaction
-+++++++++++++++++++++++
-
-To ban or kick another user in the room, or to redact an event, then the user
-must have a power level of at least that specificied in the
-`m.room.power_level` event for kick, ban and redactions.
-
-
-Other Events
-++++++++++++
-
-A user may send an event if all the following hold true:
-
-  * The user is in the room.
-  * If the type of the event is listed in the `m.room.power_levels`, then the
-    user must have at least that power level. Otherwise, the user must have a
-    power level of at least `events_default` or `state_default`, depending on
-    if the event is a message or state event respectively.
-
-
-Unauthorized Events
--------------------
-
-An unauthorized event should not be accepted into the event graph, i.e. new
-events should not reference any unauthorized events. There are situations where
-this can happen and so it is not considered an error to include an unauthorized
-event in the event graph. It is an error for events to refer unauthorized
-events in their `auth_events` section and will in turn be considered
-unauthorized.
-
-A server may choose to store only the redacted form of an unauthorized event if
-it is included in the event graph.
-
-A server may emit a warning to a remote server if it references an event it
-considers unauthorized.
-
-
-State and Authorization Querying
---------------------------------
-
-A local server may become aware that it and a remote server's view of the
-current state are inconsistent. The local server may then send its current
-state to the remote, which responds with its view of the current state. Both
-servers should then recompute the local state. If they are conforming
-implementations then they will reach the same conclusions.
-

drafts/human-id-rules.rst

@@ -1,81 +0,0 @@
-This document outlines the format for human-readable IDs within matrix.
-
-Overview
---------
-UTF-8 is quickly becoming the standard character encoding set on the web. As
-such, Matrix requires that all strings MUST be encoded as UTF-8. However,
-using Unicode as the character set for human-readable IDs is troublesome. There
-are many different characters which appear identical to each other, but would
-identify different users. In addition, there are non-printable characters which
-cannot be rendered by the end-user. This opens up a security vulnerability with
-phishing/spoofing of IDs, commonly known as a homograph attack.
-
-Web browers encountered this problem when International Domain Names were
-introduced. A variety of checks were put in place in order to protect users. If
-an address failed the check, the raw punycode would be displayed to
-disambiguate the address. Similar checks are performed by homeservers in
-Matrix. However, Matrix does not use punycode representations, and so does not
-show raw punycode on a failed check. Instead, homeservers must outright reject
-these misleading IDs.
-
-Types of human-readable IDs
----------------------------
-There are two main human-readable IDs in question:
-
-- Room aliases
-- User IDs
-
-Room aliases look like ``#localpart:domain``. These aliases point to opaque
-non human-readable room IDs. These pointers can change, so there is already an
-issue present with the same ID pointing to a different destination at a later
-date.
-
-User IDs look like ``@localpart:domain``. These represent actual end-users, and
-unlike room aliases, there is no layer of indirection. This presents a much
-greater concern with homograph attacks.
-
-Checks
-------
-- Similar to web browsers.
-- blacklisted chars (e.g. non-printable characters)
-- mix of language sets from 'preferred' language not allowed.
-- Language sets from CLDR dataset.
-- Treated in segments (localpart, domain)
-- Additional restrictions for ease of processing IDs.
-
-  - Room alias localparts MUST NOT have ``#`` or ``:``.
-  - User ID localparts MUST NOT have ``@`` or ``:``.
-
-Rejecting
----------
-- Homeservers MUST reject room aliases which do not pass the check, both on 
-  GETs and PUTs.
-- Homeservers MUST reject user ID localparts which do not pass the check, both
-  on creation and on events.
-- Any homeserver whose domain does not pass this check, MUST use their punycode
-  domain name instead of the IDN, to prevent other homeservers rejecting you.
-- Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing 
-  due to homograph attacks, and failing due to including ``:`` s, etc)
-- Error message MAY go into further information about which characters were
-  rejected and why.
-- Error message SHOULD contain a ``failed_keys`` key which contains an array
-  of strings which represent the keys which failed the check e.g::
-
-    failed_keys: [ user_id, room_alias ]
-
-Other considerations
---------------------
-- Basic security: Informational key on the event attached by HS to say "unsafe
-  ID". Problem: clients can just ignore it, and since it will appear only very
-  rarely, easy to forget when implementing clients.
-- Moderate security: Requires client handshake. Forces clients to implement
-  a check, else they cannot communicate with the misleading ID. However, this
-  is extra overhead in both client implementations and round-trips.
-- High security: Outright rejection of the ID at the point of creation /
-  receiving event. Point of creation rejection is preferable to avoid the ID
-  entering the system in the first place. However, malicious HSes can just
-  allow the ID. Hence, other homeservers must reject them if they see them in
-  events. Client never sees the problem ID, provided the HS is correctly
-  implemented.
-- High security decided; client doesn't need to worry about it, no additional
-  protocol complexity aside from rejection of an event.

drafts/macaroons_caveats.rst

@@ -1,43 +0,0 @@
-Macaroon Caveats
-================
-
-`Macaroons`_ are issued by Matrix servers as authorization tokens. Macaroons may be restricted by adding caveats to them.
-
-.. _Macaroons: http://theory.stanford.edu/~ataly/Papers/macaroons.pdf
-
-Caveats can only be used for reducing the scope of a token, never for increasing it. Servers are required to reject any macroon with a caveat that they do not understand.
-
-Some caveats are specified in this specification, and must be understood by all servers. The use of non-standard caveats is allowed.
-
-All caveats must take the form::
-
-  key operator value
-
-where:
- - ``key`` is a non-empty string drawn from the character set [A-Za-z0-9_]
- - ``operator`` is a non-empty string which does not contain whitespace
- - ``value`` is a non-empty string
- 
-And these are joined by single space characters.
-
-Specified caveats:
-
-+-------------+--------------------------------------------------+------------------------------------------------------------------------------------------------+
-| Caveat name | Description                                      | Legal Values                                                                                   |
-+=============+==================================================+================================================================================================+
-| gen         | Generation of the macaroon caveat spec.          | 1                                                                                              |
-+-------------+--------------------------------------------------+------------------------------------------------------------------------------------------------+
-| user_id     | ID of the user for which this macaroon is valid. | Pure equality check. Operator must be =.                                                       |
-+-------------+--------------------------------------------------+------------------------------------------------------------------------------------------------+
-| type        | The purpose of this macaroon.                    | - ``access``: used to authorize any action except token refresh                                |
-|             |                                                  | -  ``refresh``: only used to authorize a token refresh                                         |
-|             |                                                  | - ``login``: issued as a very short-lived token by third party login flows; proves that        |
-|             |                                                  |   authentication has happened but doesn't grant any privileges other than being able to be     |
-|             |                                                  |   exchanged for other tokens.                                                                  |
-+-------------+--------------------------------------------------+------------------------------------------------------------------------------------------------+
-| time        | Time before/after which this macaroon is valid.  | A POSIX timestamp in milliseconds (in UTC).                                                    |
-|             |                                                  | Operator < means the macaroon is valid before the timestamp, as interpreted by the server.     |
-|             |                                                  | Operator > means the macaroon is valid after the timestamp, as interpreted by the server.      |
-|             |                                                  | Operator == means the macaroon is valid at exactly the timestamp, as interpreted by the server.|
-|             |                                                  | Note that exact equality of time is largely meaningless.                                       |
-+-------------+--------------------------------------------------+------------------------------------------------------------------------------------------------+

drafts/model/presence.rst

@@ -1,149 +0,0 @@
-API Efficiency
-==============
-
-A simple implementation of presence messaging has the ability to cause a large
-amount of Internet traffic relating to presence updates. In order to minimise
-the impact of such a feature, the following observations can be made:
-
- * There is no point in a homeserver polling status for peers in a user's
-   presence list if the user has no clients connected that care about it.
-
- * It is highly likely that most presence subscriptions will be symmetric - a
-   given user watching another is likely to in turn be watched by that user.
-
- * It is likely that most subscription pairings will be between users who share
-   at least one Room in common, and so their homeservers are actively
-   exchanging message PDUs or transactions relating to that Room.
-
- * Presence update messages do not need realtime guarantees. It is acceptable to
-   delay delivery of updates for some small amount of time (10 seconds to a
-   minute).
-
-The general model of presence information is that of a HS registering its
-interest in receiving presence status updates from other HSes, which then
-promise to send them when required. Rather than actively polling for the
-current state all the time, HSes can rely on their relative stability to only
-push updates when required.
-
-A homeserver should not rely on the longterm validity of this presence
-information, however, as this would not cover such cases as a user's server
-crashing and thus failing to inform their peers that users it used to host are
-no longer available online. Therefore, each promise of future updates should
-carry with a timeout value (whether explicit in the message, or implicit as some
-defined default in the protocol), after which the receiving HS should consider
-the information potentially stale and request it again.
-
-However, because of the likelihood that two homeservers are exchanging messages
-relating to chat traffic in a room common to both of them, the ongoing receipt
-of these messages can be taken by each server as an implicit notification that
-the sending server is still up and running, and therefore that no status changes
-have happened; because if they had the server would have sent them. A second,
-larger timeout should be applied to this implicit inference however, to protect
-against implementation bugs or other reasons that the presence state cache may
-become invalid; eventually the HS should re-enquire the current state of users
-and update them with its own.
-
-The following workflows can therefore be used to handle presence updates:
-
- 1 When a user first appears online their HS sends a message to each other HS
-   containing at least one user to be watched; each message carrying both a
-   notification of the sender's new online status, and a request to obtain and
-   watch the target users' presence information. This message implicitly
-   promises the sending HS will now push updates to the target HSes.
-
- 2 The target HSes then respond a single message each, containing the current
-   status of the requested user(s). These messages too implicitly promise the
-   target HSes will themselves push updates to the sending HS.
-
-   As these messages arrive at the sending user's HS they can be pushed to the
-   user's client(s), possibly batched again to ensure not too many small
-   messages which add extra protocol overheads.
-
-At this point, all the user's clients now have the current presence status
-information for this moment in time, and have promised to send each other
-updates in future.
-
- 3 The HS maintains two watchdog timers per peer HS it is exchanging presence
-   information with. The first timer should have a relatively small expiry
-   (perhaps 1 minute), and the second timer should have a much longer time
-   (perhaps 1 hour).
-
- 4 Any time any kind of message is received from a peer HS, the short-term
-   presence timer associated with it is reset.
-
- 5 Whenever either of these timers expires, an HS should push a status reminder
-   to the target HS whose timer has now expired, and request again from that
-   server the status of the subscribed users.
-
- 6 On receipt of one of these presence status reminders, an HS can reset both
-   of its presence watchdog timers.
-
-To avoid bursts of traffic, implementations should attempt to stagger the expiry
-of the longer-term watchdog timers for different peer HSes.
-
-When individual users actively change their status (either by explicit requests
-from clients, or inferred changes due to idle timers or client timeouts), the HS
-should batch up any status changes for some reasonable amount of time (10
-seconds to a minute). This allows for reduced protocol overheads in the case of
-multiple messages needing to be sent to the same peer HS; as is the likely
-scenario in many cases, such as a given human user having multiple user
-accounts.
-
-
-API Requirements
-================
-
-The data model presented here puts the following requirements on the APIs:
-
-Client-Server
--------------
-
-Requests that a client can make to its homeserver
-
- * get/set current presence state
-   Basic enumeration + ability to set a custom piece of text
-
- * report per-device idle time
-   After some (configurable?) idle time the device should send a single message
-   to set the idle duration. The HS can then infer a "start of idle" instant and
-   use that to keep the device idleness up to date. At some later point the
-   device can cancel this idleness.
-
- * report per-device type
-   Inform the server that this device is a "mobile" device, or perhaps some
-   other to-be-defined category of reduced capability that could be presented to
-   other users.
-
- * start/stop presence polling for my presence list
-   It is likely that these messages could be implicitly inferred by other
-   messages, though having explicit control is always useful.
-
- * get my presence list
-   [implicit poll start?]
-   It is possible that the HS doesn't yet have current presence information when
-   the client requests this. There should be a "don't know" type too.
-
- * add/remove a user to my presence list
-
-Server-Server
--------------
-
-Requests that homeservers make to others
-
- * request permission to add a user to presence list
-
- * allow/deny a request to add to a presence list
-
- * perform a combined presence state push and subscription request
-   For each sending user ID, the message contains their new status.
-   For each receiving user ID, the message should contain an indication on
-   whether the sending server is also interested in receiving status from that
-   user; either as an immediate update response now, or as a promise to send
-   future updates.
-
-Server to Client
-----------------
-
-[[TODO(paul): There also needs to be some way for a user's HS to push status
-updates of the presence list to clients, but the general server-client event
-model currently lacks a space to do that.]]

drafts/model/profiles.rst

@@ -1,231 +0,0 @@
-========
-Profiles
-========
-
-A description of Synapse user profile metadata support.
-
-
-Overview
-========
-
-Internally within Synapse users are referred to by an opaque ID, which consists
-of some opaque localpart combined with the domain name of their homeserver.
-Obviously this does not yield a very nice user experience; users would like to
-see readable names for other users that are in some way meaningful to them.
-Additionally, users like to be able to publish "profile" details to inform other
-users of other information about them.
-
-It is also conceivable that since we are attempting to provide a
-worldwide-applicable messaging system, that users may wish to present different
-subsets of information in their profile to different other people, from a
-privacy and permissions perspective.
-
-A Profile consists of a display name, an (optional?) avatar picture, and a set
-of other metadata fields that the user may wish to publish (email address, phone
-numbers, website URLs, etc...). We put no requirements on the display name other
-than it being a valid Unicode string. Since it is likely that users will end up
-having multiple accounts (perhaps by necessity of being hosted in multiple
-places, perhaps by choice of wanting multiple distinct identifies), it would be
-useful that a metadata field type exists that can refer to another Synapse User
-ID, so that clients and HSes can make use of this information.
-
-Metadata Fields
----------------
-
-[[TODO(paul): Likely this list is incomplete; more fields can be defined as we
-think of them. At the very least, any sort of supported ID for the 3rd Party ID
-servers should be accounted for here.]]
-
- * Synapse Directory Server username(s)
-
- * Email address
-
- * Phone number - classify "home"/"work"/"mobile"/custom?
- 
- * Twitter/Facebook/Google+/... social networks
-
- * Location - keep this deliberately vague to allow people to choose how
-     granular it is
- 
- * "Bio" information - date of birth, etc...
-
- * Synapse User ID of another account
-
- * Web URL
-
- * Freeform description text
-
-
-Visibility Permissions
-======================
-
-A homeserver implementation could offer the ability to set permissions on
-limited visibility of those fields. When another user requests access to the
-target user's profile, their own identity should form part of that request. The
-HS implementation can then decide which fields to make available to the
-requestor.
-
-A particular detail of implementation could allow the user to create one or more
-ACLs; where each list is granted permission to see a given set of non-public
-fields (compare to Google+ Circles) and contains a set of other people allowed
-to use it. By giving these ACLs strong identities within the HS, they can be
-referenced in communications with it, granting other users who encounter these
-the "ACL Token" to use the details in that ACL.
-
-If we further allow an ACL Token to be present on Room join requests or stored
-by 3PID servers, then users of these ACLs gain the extra convenience of not
-having to manually curate people in the access list; anyone in the room or with
-knowledge of the 3rd Party ID is automatically granted access. Every HS and
-client implementation would have to be aware of the existence of these ACL
-Token, and include them in requests if present, but not every HS implementation
-needs to actually provide the full permissions model. This can be used as a
-distinguishing feature among competing implementations. However, servers MUST
-NOT serve profile information from a cache if there is a chance that its limited
-understanding could lead to information leakage.
-
-
-Client Concerns of Multiple Accounts
-====================================
-
-Because a given person may want to have multiple Synapse User accounts, client
-implementations should allow the use of multiple accounts simultaneously
-(especially in the field of mobile phone clients, which generally don't support
-running distinct instances of the same application). Where features like address
-books, presence lists or rooms are presented, the client UI should remember to
-make distinct with user account is in use for each.
-
-
-Directory Servers
-=================
-
-Directory Servers can provide a forward mapping from human-readable names to
-User IDs. These can provide a service similar to giving domain-namespaced names
-for Rooms; in this case they can provide a way for a user to reference their
-User ID in some external form (e.g. that can be printed on a business card).
-
-The format for Synapse user name will consist of a localpart specific to the
-directory server, and the domain name of that directory server:
-
-  @localname:some.domain.name
-
-The localname is separated from the domain name using a colon, so as to ensure
-the localname can still contain periods, as users may want this for similarity
-to email addresses or the like, which typically can contain them. The format is
-also visually quite distinct from email addresses, phone numbers, etc... so
-hopefully reasonably "self-describing" when written on e.g. a business card
-without surrounding context.
-
-[[TODO(paul): we might have to think about this one - too close to email?
-  Twitter? Also it suggests a format scheme for room names of
-  #localname:domain.name, which I quite like]]
-
-Directory server administrators should be able to make some kind of policy
-decision on how these are allocated. Servers within some "closed" domain (such
-as company-specific ones) may wish to verify the validity of a mapping using
-their own internal mechanisms; "public" naming servers can operate on a FCFS
-basis. There are overlapping concerns here with the idea of the 3rd party
-identity servers as well, though in this specific case we are creating a new
-namespace to allocate names into.
-
-It would also be nice from a user experience perspective if the profile that a
-given name links to can also declare that name as part of its metadata.
-Furthermore as a security and consistency perspective it would be nice if each
-end (the directory server and the user's homeserver) check the validity of the
-mapping in some way. This needs investigation from a security perspective to
-ensure against spoofing.
-
-One such model may be that the user starts by declaring their intent to use a
-given user name link to their homeserver, which then contacts the directory
-service. At some point later (maybe immediately for "public open FCFS servers",
-maybe after some kind of human intervention for verification) the DS decides to
-honour this link, and includes it in its served output. It should also tell the
-HS of this fact, so that the HS can present this as fact when requested for the
-profile information. For efficiency, it may further wish to provide the HS with
-a cryptographically-signed certificate as proof, so the HS serving the profile
-can provide that too when asked, avoiding requesting HSes from constantly having
-to contact the DS to verify this mapping. (Note: This is similar to the security
-model often applied in DNS to verify PTR <-> A bidirectional mappings).
-
-
-Identity Servers
-================
-
-The identity servers should support the concept of pointing a 3PID being able to
-store an ACL Token as well as the main User ID. It is however, beyond scope to
-do any kind of verification that any third-party IDs that the profile is
-claiming match up to the 3PID mappings.
-
-
-User Interface and Expectations Concerns
-========================================
-
-Given the weak "security" of some parts of this model as compared to what users
-might expect, some care should be taken on how it is presented to users,
-specifically in the naming or other wording of user interface components.
-
-Most notably mere knowledge of an ACL Pointer is enough to read the information
-stored in it. It is possible that Home or Identity Servers could leak this
-information, allowing others to see it. This is a security-vs-convenience
-balancing choice on behalf of the user who would choose, or not, to make use of
-such a feature to publish their information.
-
-Additionally, unless some form of strong end-to-end user-based encryption is
-used, a user of ACLs for information privacy has to trust other homeservers not
-to lie about the identify of the user requesting access to the Profile.
-
-
-API Requirements
-================
-
-The data model presented here puts the following requirements on the APIs:
-
-Client-Server
--------------
-
-Requests that a client can make to its homeserver
-
- * get/set my Display Name
-   This should return/take a simple "text/plain" field
-
- * get/set my Avatar URL
-   The avatar image data itself is not stored by this API; we'll just store a
-   URL to let the clients fetch it. Optionally HSes could integrate this with
-   their generic content attacmhent storage service, allowing a user to set
-   upload their profile Avatar and update the URL to point to it.
-
- * get/add/remove my metadata fields
-   Also we need to actually define types of metadata
-
- * get another user's Display Name / Avatar / metadata fields
-
-TODO(paul): At some later stage we should consider the API for:
-
- * get/set ACL permissions on my metadata fields
-
- * manage my ACL tokens
-
-Server-Server
--------------
-
-Requests that homeservers make to others
-
- * get a user's Display Name / Avatar
-
- * get a user's full profile - name/avatar + MD fields
-   This request must allow for specifying the User ID of the requesting user,
-   for permissions purposes. It also needs to take into account any ACL Tokens
-   the requestor has.
-
- * push a change of Display Name to observers (overlaps with the presence API)
-
-Room Event PDU Types
---------------------
-
-Events that are pushed from homeservers to other homeservers or clients.
-
- * user Display Name change
- 
- * user Avatar change
-   [[TODO(paul): should the avatar image itself be stored in all the room
-   histories? maybe this event should just be a hint to clients that they should
-   re-fetch the avatar image]]

drafts/model/protocol_examples.rst

@@ -1,68 +0,0 @@
-PUT /send/abc/ HTTP/1.1
-Host: ...
-Content-Length: ...
-Content-Type: application/json
-
-.. code :: javascript
-
-  {
-    "origin": "localhost:5000",
-    "pdus": [
-        {
-            "content": {},
-            "context": "tng",
-            "depth": 12,
-            "is_state": false,
-            "origin": "localhost:5000",
-            "pdu_id": 1404381396854,
-            "pdu_type": "feedback",
-            "prev_pdus": [
-                [
-                    "1404381395883",
-                    "localhost:6000"
-                ]
-            ],
-            "ts": 1404381427581
-        }
-    ],
-    "prev_ids": [
-        "1404381396852"
-    ],
-    "ts": 1404381427823
-  }
-
-HTTP/1.1 200 OK
-
-
-======================================
-
-GET /pull/-1/ HTTP/1.1
-Host: ...
-Content-Length: 0
-
-HTTP/1.1 200 OK
-Content-Length: ...
-Content-Type: application/json
-
-.. code :: javascript
-
-  {
-    origin: ...,
-    prev_ids: ...,
-    data: [
-        {
-            data_id: ...,
-            prev_pdus: [...],
-            depth: ...,
-            ts: ...,
-            context: ...,
-            origin: ...,
-            content: {
-                ...
-            }
-        },
-        ...,
-    ]
-  }
-
-

drafts/model/room-join-workflow.rst

@@ -1,113 +0,0 @@
-==================
-Room Join Workflow
-==================
-
-An outline of the workflows required when a user joins a room.
-
-Discovery
-=========
-
-To join a room, a user has to discover the room by some mechanism in order to
-obtain the (opaque) Room ID and a candidate list of likely homeservers that
-contain it.
-
-Sending an Invitation
----------------------
-
-The most direct way a user discovers the existence of a room is from a
-invitation from some other user who is a member of that room.
-
-The inviter's HS sets the membership status of the invitee to "invited" in the
-"m.members" state key by sending a state update PDU. The HS then broadcasts this
-PDU among the existing members in the usual way. An invitation message is also
-sent to the invited user, containing the Room ID and the PDU ID of this
-invitation state change and potentially a list of some other homeservers to use
-to accept the invite. The user's client can then choose to display it in some
-way to alert the user.
-
-[[TODO(paul): At present, no API has been designed or described to actually send
-that invite to the invited user. Likely it will be some facet of the larger
-user-user API required for presence, profile management, etc...]]
-
-Directory Service
------------------
-
-Alternatively, the user may discover the channel via a directory service; either
-by performing a name lookup, or some kind of browse or search acitivty. However
-this is performed, the end result is that the user's homeserver requests the
-Room ID and candidate list from the directory service.
-
-[[TODO(paul): At present, no API has been designed or described for this
-directory service]]
-
-
-Joining
-=======
-
-Once the ID and homeservers are obtained, the user can then actually join the
-room.
-
-Accepting an Invite
--------------------
-
-If a user has received and accepted an invitation to join a room, the invitee's
-homeserver can now send an invite acceptance message to a chosen candidate
-server from the list given in the invitation, citing also the PDU ID of the
-invitation as "proof" of their invite. (This is required as due to late message
-propagation it could be the case that the acceptance is received before the
-invite by some servers). If this message is allowed by the candidate server, it
-generates a new PDU that updates the invitee's membership status to "joined",
-referring back to the acceptance PDU, and broadcasts that as a state change in
-the usual way. The newly-invited user is now a full member of the room, and
-state propagation proceeds as usual.
-
-Joining a Public Room
----------------------
-
-If a user has discovered the existence of a room they wish to join but does not
-have an active invitation, they can request to join it directly by sending a
-join message to a candidate server on the list provided by the directory
-service. As this list may be out of date, the HS should be prepared to retry
-other candidates if the chosen one is no longer aware of the room, because it
-has no users as members in it.
-
-Once a candidate server that is aware of the room has been found, it can
-broadcast an update PDU to add the member into the "m.members" key setting their
-state directly to "joined" (i.e. bypassing the two-phase invite semantics),
-remembering to include the new user's HS in that list.
-
-Knocking on a Semi-Public Room
-------------------------------
-
-If a user requests to join a room but the join mode of the room is "knock", the
-join is not immediately allowed. Instead, if the user wishes to proceed, they
-can instead post a "knock" message, which informs other members of the room that
-the would-be joiner wishes to become a member and sets their membership value to
-"knocked". If any of them wish to accept this, they can then send an invitation
-in the usual way described above. Knowing that the user has already knocked and
-expressed an interest in joining, the invited user's homeserver should
-immediately accept that invitation on the user's behalf, and go on to join the
-room in the usual way.
-
-[[NOTE(Erik): Though this may confuse users who expect 'X has joined' to
-actually be a user initiated action, i.e. they may expect that 'X' is actually
-looking at synapse right now?]]
-
-[[NOTE(paul): Yes, a fair point maybe we should suggest HSes don't do that, and
-just offer an invite to the user as normal]]
-
-Private and Non-Existent Rooms
-------------------------------
-
-If a user requests to join a room but the room is either unknown by the home
-server receiving the request, or is known by the join mode is "invite" and the
-user has not been invited, the server must respond that the room does not exist.
-This is to prevent leaking information about the existence and identity of
-private rooms.
-
-
-Outstanding Questions
-=====================
-
- * Do invitations or knocks time out and expire at some point? If so when? Time
-   is hard in distributed systems.