.github/CODEOWNERS

@@ -1 +0,0 @@
-*       @matrix-org/spec-core-team

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/clarification.md

@@ -1,13 +0,0 @@
----
-name: Clarity problem
-about: Report an area of the spec that is unclear.
-title: ''
-labels: 'clarification'
-assignees: ''
-
----
-
-**Link to problem area**:
-
-**Issue**
-What is wrong? How can we improve?

.github/ISSUE_TEMPLATE/config.yaml

@@ -1,8 +0,0 @@
-blank_issues_enabled: false
-contact_links:
- - name: Matrix Spec Discussion
-   url: "https://matrix.to/#/#matrix-spec:matrix.org"
-   about: Questions about the spec and proposal process can be asked here.
- - name: Matrix Security Policy
-   url: https://www.matrix.org/security-disclosure-policy/
-   about: Learn more about our security disclosure policy.

.github/ISSUE_TEMPLATE/cosmetic-bug.md

@@ -1,13 +0,0 @@
----
-name: Cosmetic issue
-about: Report an issue with how the spec looks.
-title: ''
-labels: 'aesthetic'
-assignees: ''
-
----
-
-**Link to problem area**:
-
-**Issue**
-What is wrong? What can we do to improve?

.github/ISSUE_TEMPLATE/idea.md

@@ -1,12 +0,0 @@
----
-name: Spec idea
-about: Suggest a future MSC idea.
-title: ''
-labels: 'improvement'
-assignees: ''
-
----
-
-**Suggestion**
-What would you like to see in Matrix? If your idea is vaguely complete enough, we
-recommend submitting [an MSC](https://matrix.org/docs/spec/proposals) instead.

.github/ISSUE_TEMPLATE/release.md

@@ -1,37 +0,0 @@
----
-name: '[SCT] Release checklist'
-about: 'Used by the Spec Core Team to create a new release.'
-title: 'Matrix 1.X'
-labels: 'release-blocker'
-assignees: ''
-
----
-
-<!-- ------------------------------------------------------------------------ -->
-<!-- Please asssign the release coordinator (probably yourself) to this issue -->
-<!-- ------------------------------------------------------------------------ -->
-
-Date: **Thursday, May 25, 2023** <!-- CHANGE ME -->
-Previous release: <!-- LINK TO LAST RELEASE'S CHECKLIST -->
-
-Preflight checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
-
-* [ ] Pin this issue to the repo.
-* [ ] Ensure the social media account holders are available for the release day.
-* [ ] Blog post written.
-* [ ] Check for release blockers that may have been missed.
-* [ ] Review/fix the changelog.
-
-Release checklist ([release steps](https://github.com/matrix-org/matrix-spec/blob/main/meta/releasing.md)):
-* [ ] Branch stuffs.
-* [ ] Github release artifact.
-* [ ] Published to spec.matrix.org.
-* [ ] All links work.
-* [ ] Publish blog post.
-* [ ] Announce in #matrix-spec, client developers, HS developers, SCT office, and other rooms as warranted.
-* [ ] Post to Twitter/Mastodon.
-* [ ] Close this issue.
-* [ ] Unpin this issue from the repo.
-
-Known release blockers:
-* [ ] <!-- Issue/PR link -->

.github/ISSUE_TEMPLATE/spec-bug.md

@@ -1,16 +0,0 @@
----
-name: Documentation error
-about: Report an issue with the spec itself (incorrect text).
-title: ''
-labels: 'spec-bug'
-assignees: ''
-
----
-
-**Link to problem area**:
-
-**Issue**
-What is wrong?
-
-**Expected behaviour**
-How can the issue be fixed? Links to implementations/documents which prove the spec is wrong are appreciated.

.github/_typos.toml

@@ -1,13 +0,0 @@
-[files]
-extend-exclude = ["/themes", "/attic", "/data-definitions", "*.css", "syntax.scss", "package-lock.json"]
-
-[default]
-check-filename = true
-
-[default.extend-identifiers]
-au1ba7o = "au1ba7o"
-
-[default.extend-words]
-Appy = "Appy"
-fo = "fo"
-Iy = "Iy"

.github/pull_request_template.md

@@ -1,8 +0,0 @@
-
-### Pull Request Checklist
-
-<!-- Please read CONTRIBUTING.rst before submitting your pull request -->
-
-* [ ] Pull request includes a [changelog file](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#adding-to-the-changelog)
-* [ ] Pull request includes a [sign off](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#sign-off)
-* [ ] Pull request is classified as ['other changes'](https://github.com/matrix-org/matrix-spec/blob/master/CONTRIBUTING.rst#other-changes)

.github/workflows/checks.yaml

@@ -1,18 +0,0 @@
-# workflow steps that ought to pass on a PR, but shouldn't block a preview.
-
-name: "Checks"
-on:
-  pull_request:
- 
-jobs:
-  check-newsfragments:
-    name: "🔎 Check that new newsfragments are valid"
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - run: scripts/check-newsfragments
-        env:
-          PULL_REQUEST_NUMBER: ${{ github.event.number }}

.github/workflows/main.yml

@@ -1,312 +0,0 @@
-name: "Spec"
-
-env:
-  HUGO_VERSION: 0.148.1
-  PYTHON_VERSION: 3.13
-
-on:
-  push:
-    branches:
-      - main
-    tags:
-      - v*
-  pull_request:
-  workflow_dispatch:
-  schedule:
-    # Run this workflow every day at 2am. This helps keep the page of
-    # current spec proposals up-to-date.
-    - cron: '0 2 * * *'
-
-jobs:
-  validate-openapi:
-    name: "🔎 Validate OpenAPI specifications"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: "🔎 Run validator"
-        run: |
-          npx @redocly/cli@latest lint data/api/*/*.yaml
-
-  check-event-examples:
-    name: "🔎 Check Event schema examples"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-          cache-dependency-path: scripts/requirements.txt
-      - name: "➕ Install dependencies"
-        run: |
-          pip install -r scripts/requirements.txt
-      - name: "🔎 Run validator"
-        run: |
-          python scripts/check-event-schema-examples.py
-
-  check-openapi-examples:
-    name: "🔎 Check OpenAPI definitions examples"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-          cache-dependency-path: scripts/requirements.txt
-      - name: "➕ Install dependencies"
-        run: |
-          pip install -r scripts/requirements.txt
-      - name: "🔎 Run validator"
-        run: |
-          python scripts/check-openapi-sources.py
-
-  check-schemas-examples:
-    name: "🔎 Check JSON Schemas inline examples"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-          cache-dependency-path: scripts/requirements.txt
-      - name: "➕ Install dependencies"
-        run: |
-          pip install -r scripts/requirements.txt
-      - name: "🔎 Run validator"
-        run: |
-          python scripts/check-json-schemas.py
-
-  calculate-baseurl:
-    name: "⚙️ Calculate baseURL for later jobs"
-    runs-on: ubuntu-latest
-    outputs:
-      baseURL: "${{ steps.set-baseurl.outputs.baseURL }}"
-    steps:
-      # For PRs, set the baseURL to `/`.
-      # For releases, set the baseURL to `/$tag` (eg: `/v1.2`).
-      # Otherwise, set it to `/unstable`.
-      - name: "⚙️ Calculate baseURL"
-        id: set-baseurl
-        # Double brackets on the elif to avoid auto-escaping refs/tags/* because we need
-        # the asterisk matching behaviour, not the literal string.
-        run: |
-          if [ "${GITHUB_EVENT_NAME}" == "pull_request" ]; then
-              echo "baseURL=/" >> "$GITHUB_OUTPUT"
-          elif [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-              echo "baseURL=/${GITHUB_REF/refs\/tags\//}" >> "$GITHUB_OUTPUT"
-          else
-              echo "baseURL=/unstable" >> "$GITHUB_OUTPUT"
-          fi
-
-  build-openapi:
-    name: "🐍 Build OpenAPI definitions"
-    runs-on: ubuntu-latest
-    needs: [calculate-baseurl]
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-          cache: 'pip'
-          cache-dependency-path: scripts/requirements.txt
-      - name: "➕ Install dependencies"
-        run: |
-          pip install -r scripts/requirements.txt
-      - name: "📦 Asset creation"
-        run: |
-          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
-            export RELEASE="${GITHUB_REF/refs\/tags\//}"
-          else
-            export RELEASE="unstable"
-          fi
-          # The output path matches the final deployment path at spec.matrix.org
-          scripts/dump-openapi.py \
-            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-            --api application-service \
-            -r "$RELEASE" \
-            -o spec/application-service-api/api.json
-          scripts/dump-openapi.py \
-            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-            --api client-server \
-            -r "$RELEASE" \
-            -o spec/client-server-api/api.json
-          scripts/dump-openapi.py \
-            --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-            --api push-gateway \
-            -r "$RELEASE" \
-            -o spec/push-gateway-api/api.json
-          scripts/dump-openapi.py \
-              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-              --api server-server \
-              -r "$RELEASE" \
-              -o spec/server-server-api/api.json
-          scripts/dump-openapi.py \
-              --base-url "https://spec.matrix.org${{ needs.calculate-baseurl.outputs.baseURL }}" \
-              --api identity \
-              -r "$RELEASE" \
-              -o spec/identity-service-api/api.json
-          tar -czf openapi.tar.gz spec
-      - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
-        with:
-          name: openapi-artifact
-          path: openapi.tar.gz
-
-  generate-changelog:
-    name: "📢 Run towncrier for changelog"
-    # skip for builds of git tags
-    if: "!startsWith(github.ref, 'refs/tags/')"
-    runs-on: ubuntu-latest
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "➕ Setup Python"
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-      - name: "➕ Install towncrier"
-        run: "pip install 'towncrier'"
-      - name: "Generate changelog"
-        run: ./scripts/generate-changelog.sh vUNSTABLE
-      - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
-        with:
-          name: changelog-artifact
-          path: content/changelog/unstable.md
-
-  build-spec:
-    name: "📖 Build the spec"
-    runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-openapi, generate-changelog]
-    # run even if generate-changelog was skipped
-    if: ${{ always() }}
-    steps:
-      - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
-        with:
-          hugo-version: ${{ env.HUGO_VERSION }}
-          extended: true
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "⚙️ npm"
-        run: |
-          npm i
-          npm run get-proposals
-      - name: "📥 Download generated changelog"
-        if: "needs.generate-changelog.result == 'success'"
-        uses: actions/download-artifact@v4
-        with:
-          name: changelog-artifact
-          path: content/changelog
-      - name: "⚙️ hugo"
-        run: hugo --baseURL "${{ needs.calculate-baseurl.outputs.baseURL }}" -d "spec"
-      # We manually unpack the spec OpenAPI definition JSON to the website tree
-      # to make it available to the world in a canonical place:
-      # https://spec.matrix.org/latest/client-server-api/api.json
-      # Works for /unstable/ and /v1.1/ as well.
-      - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v4
-        with:
-          name: openapi-artifact
-      - name: "📝 Unpack the OpenAPI definitions in the right location"
-        run: |
-          tar -xzf openapi.tar.gz
-
-      - name: "📦 Tarball creation"
-        run: tar -czf spec.tar.gz spec
-      - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
-        with:
-          name: spec-artifact
-          path: spec.tar.gz
-
-  htmlcheck:
-    name: "🔎 Validate generated HTML"
-    runs-on: ubuntu-latest
-    needs: [calculate-baseurl, build-spec]
-    steps:
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-
-      - name: "📥 Fetch built spec"
-        uses: actions/download-artifact@v4
-        with:
-          name: spec-artifact
-
-      - name: "📝 Unpack the spec"
-        # we have to unpack it into the right path given the baseurl, so that the
-        # links are correct.
-        # eg if baseurl is `/unstable`, we want to put the site in `spec/unstable`.
-        run: |
-          mkdir -p "spec${baseURL}"
-          tar -C "spec${baseURL}" --strip-components=1 -xvzf spec.tar.gz
-        env:
-          baseURL: "${{ needs.calculate-baseurl.outputs.baseURL }}"
-
-      - name: "Run htmltest"
-        uses: wjdp/htmltest-action@master
-        with:
-          config: .htmltest.yml
-
-  build-historical-spec:
-    name: "📖 Build the historical backup spec"
-    runs-on: ubuntu-latest
-    needs: [build-openapi]
-    if: ${{ startsWith(github.ref, 'refs/tags/') }}
-    steps:
-      - name: "➕ Setup Node"
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-      - name: "➕ Setup Hugo"
-        uses: peaceiris/actions-hugo@75d2e84710de30f6ff7268e08f310b60ef14033f # v3.0.0
-        with:
-          hugo-version: ${{ env.HUGO_VERSION }}
-          extended: true
-      - name: "📥 Source checkout"
-        uses: actions/checkout@v4
-      - name: "⚙️ npm"
-        run: |
-          npm i
-          npm run get-proposals
-      - name: "⚙️ hugo"
-        env:
-          HUGO_PARAMS_VERSION_STATUS: "historical"
-        # Create a baseURL like `/v1.2` out of the `v1.2` tag
-        run: |
-          hugo --baseURL "/${GITHUB_REF/refs\/tags\//}" -d "spec"
-
-      - name: "📥 Spec definition download"
-        uses: actions/download-artifact@v4
-        with:
-          name: openapi-artifact
-      - name: "📝 Unpack the OpenAPI definitions in the right location"
-        run: |
-          tar -xzf openapi.tar.gz
-
-      - name: "📦 Tarball creation"
-        run: tar -czf spec-historical.tar.gz spec
-      - name: "📤 Artifact upload"
-        uses: actions/upload-artifact@v4
-        with:
-          name: spec-historical-artifact
-          path: spec-historical.tar.gz

.github/workflows/netlify.yaml

@@ -1,72 +0,0 @@
-# GHA workflow which publishes previews of spec PRs to netlify.
-#
-# We keep this in a separate workflow to the main spec build, because it
-# requires access to the Netlify secret. By having it run on `workflow_run`, we
-# will only use the workflow definition file on the default branch, so we can
-# ensure that the secret can't be exfiltrated.
-#
-
-name: Upload Preview Build to Netlify
-on:
-  workflow_run:
-    workflows: [Spec]
-    types: [completed]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    if: github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request'
-    steps:
-      - name: "dump context data"
-        run: |
-          jq . < $GITHUB_EVENT_PATH
-          
-      - name: "🔍 Read PR number"
-        id: readctx
-        # we need to find the PR number that corresponds to the branch, which we do by
-        # searching the GH API
-        env:
-          OWNER_LOGIN: ${{ github.event.workflow_run.head_repository.owner.login }}
-          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
-        run: |
-          head_branch="${OWNER_LOGIN}:${HEAD_BRANCH}"
-          echo "head branch: $head_branch"
-          pulls_uri="https://api.github.com/repos/${{ github.repository }}/pulls?head=$(jq -Rr '@uri' <<<$head_branch)"
-          pr_number=$(curl -H 'Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' "$pulls_uri" |
-               jq -r '.[] | .number')
-          echo "PR number: $pr_number"
-          echo "prnumber=$pr_number" >> "$GITHUB_OUTPUT"
-        
-      - name: '📥 Download artifact'
-        uses: dawidd6/action-download-artifact@09f2f74827fd3a8607589e5ad7f9398816f540fe # v3.1.4
-        with:
-          workflow: main.yaml
-          run_id: ${{ github.event.workflow_run.id }}
-          name: spec-artifact
-
-      - name: "📦 Extract Artifacts"
-        run: tar -xzvf spec.tar.gz && rm spec.tar.gz
-        
-      - name: "📤 Deploy to Netlify"
-        id: netlify
-        uses: nwtgck/actions-netlify@4cbaf4c08f1a7bfa537d6113472ef4424e4eb654 # v3.0.0
-        with:
-          publish-dir: spec
-          deploy-message: "Deploy from GitHub Actions"
-          enable-pull-request-comment: false
-          enable-commit-comment: false
-          alias: pr${{ steps.readctx.outputs.prnumber }}
-        env:
-          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
-          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
-        timeout-minutes: 1
-
-      - name: "📝 Edit PR Description"
-        # v1.0.1
-        uses: Beakyn/gha-comment-pull-request@2167a7aee24f9e61ce76a23039f322e49a990409
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          pull-request-number: ${{ steps.readctx.outputs.prnumber }}
-          description-message: |
-            Preview: ${{ steps.netlify.outputs.deploy-url }}

.github/workflows/release.yaml

@@ -1,43 +0,0 @@
-name: Release packages
-on:
-  release:
-    types: [published]
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-jobs:
-  # Releases to npm after bumping the package.json version from 0.0.0 to $TAG.0 as the tags only contain MAJOR.MINOR
-  npm:
-    name: Publish to npm
-    runs-on: ubuntu-latest
-    if: github.event.release.prerelease == false
-    defaults:
-      run:
-        working-directory: packages/npm
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - name: 🧮 Checkout code
-        uses: actions/checkout@v4
-
-      - name: 🔧 Yarn cache
-        uses: actions/setup-node@v4
-        with:
-          cache: "yarn"
-          cache-dependency-path: packages/npm/yarn.lock
-          registry-url: "https://registry.npmjs.org"
-
-      # Ensure npm 11.5.1 or later is installed
-      - name: Update npm
-        run: npm install -g npm@latest
-
-      - name: 🔨 Install dependencies
-        run: "yarn install --frozen-lockfile"
-
-      # We bump the package.json version to git, we just need it for publish to do the right thing
-      - name: 🎖 Bump package.json version
-        run: "yarn version --new-version ${VERSION#v} --no-git-tag-version"
-        env:
-          VERSION: ${{ github.event.release.tag_name }}.0
-
-      - name: 🚀 Publish to npm
-        run: npm publish --provenance --access public --tag latest

.github/workflows/spell-check.yaml

@@ -1,19 +0,0 @@
-name: Spell Check
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-
-jobs:
-  run:
-    name: Spell Check with Typos
-    runs-on: ubuntu-latest
-    steps:
-    - name: Checkout Actions 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,17 +1,11 @@
-node_modules
-/data/msc
-/env*
-/resources
-/scripts/openapi
-/scripts/tmp
-/hugo-config.toml
-/public
+/api/node_modules
+/assets
+/assets.tar.gz
+/env
+/scripts/gen
+/scripts/continuserv/continuserv
+/scripts/speculator/speculator
+/scripts/swagger
+/templating/out
 *.pyc
 *.swp
-_rendered.rst
-/.vscode/
-/.idea/
-/spec/
-changelogs/rendered.*
-.hugo_build.lock
-hugo_stats.json

.htmltest.yml

@@ -1,7 +0,0 @@
-# config file for htmltest. This is used by one of the checks in Github
-# Actions.
-
-IgnoreDirectoryMissingTrailingSlash: true
-DirectoryPath: spec
-CheckExternal: false
-IgnoreInternalEmptyHash: true

.travis.yml

@@ -0,0 +1,8 @@
+language: go
+go:
+  - 1.8
+
+sudo: false
+
+script:
+  - ./scripts/test-and-build.sh

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Contributing to matrix-spec
-===========================
+Contributing to matrix-doc
+==========================
 
 Everyone is welcome to contribute to the Matrix specification!
 
@@ -9,21 +9,57 @@ Code style
 ----------
 
 The documentation style is described at
-https://github.com/matrix-org/matrix-spec/blob/main/meta/documentation_style.rst.
+https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
 
-Matrix-spec workflows
----------------------
+Python code within the ``matrix-doc`` project should follow the same style as
+synapse, which is documented at
+https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.
+
+Matrix-doc workflows
+--------------------
 
 Specification changes
 ~~~~~~~~~~~~~~~~~~~~~
 
-The Matrix specification documents the APIs which Matrix clients and servers use.
-For this to be effective, the APIs need to be present and working correctly in a
-server before they can be documented in the specification. This process can take
-some time to complete.
+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 the `Matrix Design drafts folder
+   <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.
 
-Changes to the protocol (new endpoints, ideas, etc) need to go through the
-`proposals process <https://matrix.org/docs/spec/proposals>`_.
 
 Other changes
 ~~~~~~~~~~~~~
@@ -36,79 +72,36 @@ following:
 
 * Addition of features which have been in use in practice for some time, but
   have never made it into the spec (including anything with the `spec-omission
-  <https://github.com/matrix-org/matrix-spec/labels/spec-omission>`_ label).
+  <https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_ label).
 
 * Likewise, corrections to the specification, to fix situations where, in
   practice, servers and clients behave differently to the specification,
   including anything with the `spec-bug
-  <https://github.com/matrix-org/matrix-spec/labels/spec-bug>`_ label.
+  <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_ label.
 
   (If there is any doubt about whether it is the spec or the implementations
-  that need fixing, please discuss it with us first in `#matrix-spec:matrix.org`_.)
+  that need fixing, please discuss it with us first in `#matrix-dev:matrix.org
+  <http://matrix.to/#/#matrix-dev:matrix.org>`_.)
 
 * Clarifications to the specification which do not change the behaviour of
   Matrix servers or clients in a way which might introduce compatibility
   problems for existing deployments. This includes anything with the
-  `clarification <https://github.com/matrix-org/matrix-spec/labels/clarification>`_
+  `clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
   label.
 
-  For example, areas where the specification is unclear do not require a proposal
-  to fix. On the other hand, introducing new behaviour is best represented by a
-  proposal.
+  For 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.
 
-* Design or aesthetic changes, such as improving accessibility, colour schemes,
-  etc. Please check in with us at `#matrix-docs:matrix.org`_ with your proposed
-  design change before opening a PR so we can work with you on it.
+For such changes, please do just open a `pull request`_.
 
-For such changes, please do just open a `pull request`_. If you're not sure if
-your change is covered by the above, please visit `#matrix-spec:matrix.org` and
-ask.
-
-.. _`pull request`: https://help.github.com/articles/about-pull-requests
-.. _`#matrix-spec:matrix.org`: https://matrix.to/#/#matrix-spec:matrix.org
-.. _`#matrix-docs:matrix.org`: https://matrix.to/#/#matrix-docs:matrix.org
-
-
-Adding to the changelog
-~~~~~~~~~~~~~~~~~~~~~~~
-
-All changes to the contents of this repository require a changelog entry. Adding to the changelog can only
-be done after you've opened your pull request, so be sure to do that first.
-
-The changelog is managed by `Towncrier <https://github.com/twisted/towncrier>`_ in the
-form of "news fragments". Depending on which API you changed, an entry should be added to
-each relevant API's ``newsfragments`` directory. A directory exists for each API under
-``changelogs/``. For instance, news fragments for the client-server API are stored
-under ``changelogs/client_server/newsfragments``. Any changes to the repository that do
-not affect the spec content itself, such as changes to the build script, formatting, CSS,
-etc. should be documented under ``changelogs/internal/newsfragments``.
-
-To create a changelog entry, create a file named in the format ``prNumber.type`` in
-the ``newsfragments`` directory. The ``type`` can be one of the following:
-
-* ``new`` - Used when adding new endpoints. Please have the file contents be the
-  method and route being added, surrounded in markdown code tags. For example: \`POST
-  /accounts/whoami\`.
-
-* ``feature`` - Used when adding backwards-compatible changes to the API.
-
-* ``clarification`` - Used when an area of the spec is being improved upon and does
-  not change or introduce any functionality.
-
-* ``breaking`` - Used when the change is not backwards compatible.
-
-* ``deprecation`` - Used when deprecating something.
-
-* ``removal`` - Used when removing something that was unused or previously deprecated.
-
-All news fragments must have a brief summary explaining the change in the
-contents of the file. The summary must end in a full stop to be in line with
-the style guide and formatting must be done using Markdown.
+.. _pull request: https://help.github.com/articles/about-pull-requests
 
 Sign off
 --------
 
-We ask that everybody who contributes to this project signs off their
+We ask that everybody who contributes to their project signs off their
 contributions, as explained below.
 
 We follow a simple 'inbound=outbound' model for contributions: the act of
@@ -118,10 +111,11 @@ license - in our case, this is Apache Software License v2 (see LICENSE).
 
 In order to have a concrete record that your contribution is intentional
 and you agree to license it under the same terms as the project's license, we've adopted the
-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
+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
@@ -165,6 +159,7 @@ include the line in your commit or pull request comment::
 
     Signed-off-by: Your Name <your@email.example.org>
 
-Git allows you to add this signoff automatically when using the ``-s``
-flag to ``git commit``, which uses the name and email set in your
-``user.name`` and ``user.email`` git configs.
+...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 :)

README.md

@@ -1,101 +0,0 @@
-# Matrix Specification
-
-This repository contains the Matrix Specification. The current release version is rendered at https://spec.matrix.org, while the latest available build of the `main` branch is at https://spec.matrix.org/unstable.
-
-Developers looking to use Matrix should join [#matrix-dev:matrix.org](https://matrix.to/#/#matrix-dev:matrix.org)
-on Matrix for help.
-
-Spec authors and proposal writers are welcome to join [#matrix-spec:matrix.org](https://matrix.to/#/#matrix-spec:matrix.org).
-We welcome contributions! See [CONTRIBUTING.rst](./CONTRIBUTING.rst) for details.
-
-## Structure
-
-The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site generator) with the following structure:
-
-* `/assets`: assets that need postprocessing using [Hugo Pipes](https://gohugo.io/hugo-pipes/introduction/).
-  For example, Sass files would go here.
-
-* `/content`: files that will become pages in the site go here. Typically these are Markdown files with some YAML front
-  matter indicating, [among other things](https://gohugo.io/content-management/front-matter/), what layout should be
-  applied to this page. The organization of files under `/content` determines the organization of pages in the built
-  site.
-
-* `/data`: this can contain TOML, YAML, or JSON files. Files kept here are directly available to template code as
-  [data objects](https://gohugo.io/templates/data-templates/), so templates don't need to load them from a file and
-  parse them. This is also where our OpenAPI definitions and schemas are.
-
-* `/layouts`: this contains [Hugo templates](https://gohugo.io/templates/). Some templates define the overall layout of
-  a page: for example, whether it has header, footer, sidebar, and so on.
-    * `/layouts/partials`: these templates can be called from other templates, so they can be used to factor out
-      template code that's used in more than one template. An obvious example here is something like a sidebar, where
-      several different page layouts might all include the sidebar. But also, partial templates can return values: this
-      means they can be used like functions, that can be called by multiple templates to do some common processing.
-    * `/layouts/shortcodes`: these templates can be called directly from files in `/content`.
-
-* `/static`: static files which don't need preprocessing. JS or CSS files could live here.
-
-* `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are
-  supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own
-  versions of any of the theme layouts in the base `/layouts` directory. That is, if a theme provides
-  `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of the
-  template will be used.
-
-It also has the following top-level file:
-
-* `config.toml`: site-wide configuration settings. Some of these are built-in and you can add your own. Config settings
-  defined here are available in templates. All these directories above are configurable via `config.toml` settings.
-
-Additionally, the following directories may be of interest:
-
-* `/attic`: Here contains historical sections of specification and legacy drafts for the specification.
-* `/changelogs`: Various bits of changelog for the specification areas.
-* `/data-definitions`: Bits of structured data consumable by Matrix implementations.
-* `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc).
-* `/scripts`: Various scripts for generating the spec and validating its contents.
-* `/packages`: Various packages for shipping spec files like OpenAPI bindings and data definitions.
-
-## Authoring changes to the spec
-
-Please read [CONTRIBUTING.rst](./CONTRIBUTING.rst) before authoring a change to the spec. Note that spec authoring takes
-place after an MSC has been accepted, not as part of a proposal itself.
-
-1. Install the extended version (often the OS default) of Hugo:
-   <https://gohugo.io/getting-started/installing>. Note that at least Hugo
-   v0.146.0 is required.
-
-   Alternatively, use the Docker image at
-   https://hub.docker.com/r/klakegg/hugo/. (The "extended edition" is required
-   to process the SCSS.)
-2. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed.
-3. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals"
-   page and is not required.
-4. Run `hugo serve` (or `docker run --rm -it -v $(pwd):/src -p 1313:1313
-   klakegg/hugo:ext serve`) to run a local webserver which builds whenever a file
-   change is detected. If watching doesn't appear to be working for you, try
-   adding `--disableFastRender` to the commandline.
-5. Edit the specification 🙂
-
-We use a highly customized [Docsy](https://www.docsy.dev/) theme for our generated site, which uses Bootstrap and Font
-Awesome. If you're looking at making design-related changes to the spec site, please coordinate with us in
-[#matrix-docs:matrix.org](https://matrix.to/#/#matrix-docs:matrix.org) before opening a PR.
-
-## Building the specification
-
-If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above
-steps for authoring changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the
-spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"`
-to the `hugo -d "spec"` command.
-
-For building the OpenAPI definitions, create a python3 virtualenv and activate it. Then run `pip install -r ./scripts/requirements.txt`
-and finally `python ./scripts/dump-openapi.py` to generate it to `./scripts/openapi/api-docs.json`. To make use of the generated file,
-there are a number of options:
-
-* You can open `./scripts/openapi-preview.html` in your browser, and then open the file by clicking on `Local JSON File`.
-* You can run a local HTTP server by running `./scripts/openapi-http-server.py`, and then view the documentation by
-  opening `./scripts/openapi-preview.html` in your browser.
-
-## Issue tracking
-
-Specification issues are tracked on github at <https://github.com/matrix-org/matrix-spec/issues>.
-
-See [meta/github-labels.rst](./meta/github-labels.rst) for information on what the labels mean.

README.rst

@@ -0,0 +1,194 @@
+This repository contains the Matrix specification.
+
+If you want to ask more about the specification, join us on
+`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
+
+We welcome contributions to the spec! See the notes below on `Building the
+specification`_, and `<CONTRIBUTING.rst>`_ to get started making contributions.
+
+Note that the Matrix Project lists, which were previously kept in this
+repository, are now in https://github.com/matrix-org/matrix.org.
+
+Structure of this repository
+============================
+
+- ``api`` : `OpenAPI`_ (swagger) specifications for the the HTTP APIs.
+- ``attic``: historical sections of specification for reference
+  purposes.
+- ``changelogs``: 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``: the `JSON Schema`_ for all Matrix events
+  contained in the specification, along with example JSON files.
+- ``meta``: documents outlining the processes involved when writing
+  documents, e.g. documentation style, guidelines.
+- ``scripts``: scripts to generate formatted versions of the
+  documentation, typically HTML.
+- ``specification``: the specification split up into sections.
+
+.. _OpenAPI: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
+.. _JSON Schema: http://json-schema.org/
+
+Building the specification
+==========================
+
+The Matrix Spec is generated by a set of scripts, from the RST documents, API
+specs and event schemas in this repository.
+
+Preparation
+-----------
+
+To use the scripts, it is best to create a Python virtualenv as follows::
+
+  virtualenv env
+  env/bin/pip install -r scripts/requirements.txt
+
+(Benjamin Synders has contributed a script for `Nix`_ users, which can be
+invoked with ``nix-shell scripts/contrib/shell.nix``.)
+
+.. TODO: Possibly we need some libs installed; should record what they are.
+
+.. _`Nix`: https://nixos.org/nix/
+
+Generating the specification
+----------------------------
+
+To rebuild the specification, use ``scripts/gendoc.py``::
+
+  source env/bin/activate
+  ./scripts/gendoc.py
+
+The above will write the rendered version of the specification to
+``scripts/gen``. To view it, point your browser at ``scripts/gen/index.html``.
+
+Generating the OpenAPI (Swagger) specs
+--------------------------------------
+
+`Swagger`_ is a framework for representing RESTful APIs. We use it to generate
+interactive documentation for our APIs.
+
+Before the Swagger docs can be used in the Swagger UI (or other tool expecting
+a Swagger specs, they must be combined into a single json file. This can be
+done as follows::
+
+  source env/bin/activate
+  ./dump-swagger.py
+
+By default, ``dump-swagger`` will write to ``scripts/swagger/api-docs.json``.
+
+To make use of the generated file, there are a number of options:
+
+* It can be uploaded from your filesystem to an online editor/viewer such as
+  http://editor.swagger.io/
+* You can run a local HTTP server by running
+  ``./scripts/swagger-http-server.py``, and then view the documentation via an
+  online viewer; for example, at
+  http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json
+* You can host the swagger UI yourself. See
+  https://github.com/swagger-api/swagger-ui#how-to-run for advice on how to do
+  so.
+
+.. _`Swagger`: http://swagger.io/
+
+Continuserv
+-----------
+
+Continuserv is a script which will rebuild the specification every time a file
+is changed, and will serve it to a browser over HTTP. It is intended for use by
+specification authors, so that they can quickly see the effects of their
+changes.
+
+It is written in Go, so you will need the ``go`` compiler installed on your
+computer. You will also need to install fsnotify by running::
+
+  go get gopkg.in/fsnotify.v1
+
+Then, create a virtualenv as described above under `Preparation`_,
+and::
+
+  source env/bin/activate
+  go run ./scripts/continuserv/main.go
+
+You will then be able to view the generated spec by visiting
+http://localhost:8000/index.html.
+
+Issue tracking
+==============
+
+Issues with the Matrix specification are tracked in `GitHub
+<https://github.com/matrix-org/matrix-doc/issues>`_.
+
+The following labels are used to help categorize issues:
+
+`spec-omission <https://github.com/matrix-org/matrix-doc/labels/spec-omission>`_
+--------------------------------------------------------------------------------
+
+Things which have been implemented but not currently specified. These may range
+from entire API endpoints, to particular options or return parameters.
+
+Issues with this label will have been implemented in `Synapse
+<https://github.com/matrix-org/synapse>`_. Normally there will be a design
+document in Google Docs or similar which describes the feature.
+
+Examples:
+
+* `Spec PUT /directory/list <https://github.com/matrix-org/matrix-doc/issues/417>`_
+* `Unspec'd server_name request param for /join/{roomIdOrAlias}
+  <https://github.com/matrix-org/matrix-doc/issues/904>`_
+
+`clarification <https://github.com/matrix-org/matrix-doc/labels/clarification>`_
+--------------------------------------------------------------------------------
+
+An area where the spec could do with being more explicit.
+
+Examples:
+
+* `Spec the implicit limit on /syncs
+  <https://github.com/matrix-org/matrix-doc/issues/708>`_
+
+* `Clarify the meaning of the currently_active flags in presence events
+  <https://github.com/matrix-org/matrix-doc/issues/686>`_
+
+`spec-bug <https://github.com/matrix-org/matrix-doc/labels/spec-bug>`_
+----------------------------------------------------------------------
+
+Something which is in the spec, but is wrong.
+
+Note: this is *not* for things that are badly designed or don't work well
+(for which see 'improvement' or 'feature') - it is for places where the
+spec doesn't match reality.
+
+Examples:
+
+* `swagger is wrong for directory PUT
+  <https://github.com/matrix-org/matrix-doc/issues/933>`_
+
+* `receipts section still refers to initialSync
+  <https://github.com/matrix-org/matrix-doc/issues/695>`_
+
+`improvement <https://github.com/matrix-org/matrix-doc/labels/improvement>`_
+----------------------------------------------------------------------------
+
+A suggestion for a relaatively simple improvement to the protocol.
+
+Examples:
+
+* `We need a 'remove 3PID' API so that users can remove mappings
+  <https://github.com/matrix-org/matrix-doc/issues/620>`_
+* `We should mandate that /publicRooms requires an access_token
+  <https://github.com/matrix-org/matrix-doc/issues/612>`_
+
+`feature <https://github.com/matrix-org/matrix-doc/labels/feature>`_
+--------------------------------------------------------------------
+
+A suggestion for a significant extension to the matrix protocol which
+needs considerable consideration before implementation.
+
+Examples:
+
+* `Peer-to-peer Matrix <https://github.com/matrix-org/matrix-doc/issues/710>`_
+* `Specify a means for clients to "edit" previous messages
+  <https://github.com/matrix-org/matrix-doc/issues/682>`_

api/README

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

api/application-service/application_service.yaml

@@ -0,0 +1,209 @@
+# 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.
+      operationId: sendTransaction
+      parameters:
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this set of events. Homeservers generate
+            these IDs and they are used to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          description: A list of events
+          schema:
+            type: object
+            example: {
+                "events": [
+                  {
+                    "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.
+      operationId: queryRoomByAlias
+      parameters:
+        - in: path
+          name: roomAlias
+          type: string
+          description: The room alias being queried.
+          required: true
+          x-example: "#magicforest:example.com"
+      responses:
+        200:
+          description: |-
+            The application service indicates that this room alias exists. The
+            application service MUST have created a room and associated it with
+            the queried room alias using the client-server API. Additional
+            information about the room such as its name and topic can be set
+            before responding.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              }
+          schema:
+            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.
+      operationId: queryUserById
+      parameters:
+        - in: path
+          name: userId
+          type: string
+          description: The user ID being queried.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: |-
+            The application service indicates that this user exists. The application
+            service MUST create the user using the client-server API.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver has not supplied credentials to the application service.
+            Optional error information can be included in the body of this response.
+          examples:
+            application/json: {
+                "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+              }
+          schema:
+            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

@@ -0,0 +1,127 @@
+#! /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 = schema.get('example')
+
+    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 = response.get('examples', {}).get('application/json')
+    schema = response.get('schema')
+    fileurl = "file://" + os.path.abspath(filepath)
+    if example and schema:
+        try:
+            print ("Checking response schema for: %r %r %r" % (
+                filepath, request, code
+            ))
+            # Setting the 'id' tells jsonschema where the file is so that it
+            # can correctly resolve relative $ref references in the schema
+            schema['id'] = fileurl
+            resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_yaml})
+            jsonschema.validate(example, schema, resolver=resolver)
+        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

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

api/client-server/admin.yaml

@@ -0,0 +1,114 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Administration API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/admin/whois/{userId}":
+    get:
+      summary: Gets information about a particular user.
+      description: |-
+        Gets information about a particular user.
+
+        This API may be restricted to only be called by the user being looked
+        up, or by a server admin. Server-local administrator privileges are not
+        specified in this document.
+      operationId: getWhoIs
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user to look up.
+          required: true
+          x-example: "@peter:rabbit.rocks"
+      responses:
+        200:
+          description: The lookup was successful.
+          examples:
+            application/json: {
+                "user_id": "@peter:rabbit.rocks",
+                "devices": {
+                  "teapot": {
+                    "sessions": [
+                      {
+                        "connections": [
+                          {
+                            "ip": "127.0.0.1",
+                            "last_seen": 1411996332123,
+                            "user_agent": "curl/7.31.0-DEV"
+                          },
+                          {
+                            "ip": "10.0.0.2",
+                            "last_seen": 1411996332123,
+                            "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
+                          }
+                        ]
+                      }
+                    ]
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The Matrix user ID of the user.
+              devices:
+                type: object
+                description: |-
+                  Each key is an identitfier for one of the user's devices.
+                additionalProperties:
+                  type: object
+                  title: DeviceInfo
+                  properties:
+                    sessions:
+                      type: array
+                      description: A user's sessions (i.e. what they did with an access token from one login).
+                      items:
+                        type: object
+                        title: SessionInfo
+                        properties:
+                          connections:
+                            type: array
+                            description: Information particular connections in the session.
+                            items:
+                              type: object
+                              title: ConnectionInfo
+                              properties:
+                                ip:
+                                  type: string
+                                  description: Most recently seen IP address of the session.
+                                last_seen:
+                                  type: number
+                                  description: Unix timestamp that the session was last active.
+                                user_agent:
+                                  type: string
+                                  description: User agent string last seen in the session.
+      tags:
+        - Server administration

api/client-server/administrative_contact.yaml

@@ -0,0 +1,147 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Account Administrative Contact API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/account/3pid":
+    get:
+      summary: Gets a list of a user's third party identifiers.
+      description: |-
+        Gets a list of the third party identifiers that the homeserver has
+        associated with the user's account.
+
+        This is *not* the same as the list of third party identifiers bound to
+        the user's Matrix ID in Identity Servers.
+
+        Identifiers in this list may be used by the homeserver as, for example,
+        identifiers that it will accept to reset the user's account password.
+      operationId: getAccount3PIDs
+      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.
+      operationId: post3PIDs
+      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.
+      operationId: requestTokenTo3PID
+      responses:
+        200:
+          description: An email was sent to the given address

api/client-server/banning.yaml

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

api/client-server/cas_login_redirect.yaml

@@ -0,0 +1,54 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server CAS Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+paths:
+  "/login/cas/redirect":
+    get:
+      summary: Redirect the user's browser to the CAS interface.
+      description: |-
+        A web-based Matrix client should instruct the user's browser to
+        navigate to this endpoint in order to log in via CAS.
+
+        The server MUST respond with an HTTP redirect to the CAS interface. The
+        URI MUST include a ``service`` parameter giving the path of the
+        |/login/cas/ticket|_ endpoint (including the ``redirectUrl`` query
+        parameter).
+
+        For example, if the endpoint is called with
+        ``redirectUrl=https://client.example.com/?q=p``, it might redirect to
+        ``https://cas.example.com/?service=https%3A%2F%2Fserver.example.com%2F_matrix%2Fclient%2F%CLIENT_MAJOR_VERSION%%2Flogin%2Fcas%2Fticket%3FredirectUrl%3Dhttps%253A%252F%252Fclient.example.com%252F%253Fq%253Dp``.
+
+      operationId: redirectToCAS
+      parameters:
+        - in: query
+          type: string
+          name: redirectUrl
+          description: |-
+            URI to which the user will be redirected after the homeserver has
+            authenticated the user with CAS.
+          required: true
+      responses:
+        302:
+          description: A redirect to the CAS interface.
+          headers:
+            Location:
+              type: "string"

api/client-server/cas_login_ticket.yaml

@@ -0,0 +1,66 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server CAS Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+paths:
+  "/login/cas/ticket":
+    get:
+      summary: Receive and validate a CAS login ticket.
+      description: |-
+        Once the CAS server has authenticated the user, it will redirect the
+        browser to this endpoint (assuming |/login/cas/redirect|_ gave it the
+        correct ``service`` parameter).
+
+        The server MUST call ``/proxyValidate`` on the CAS server, to validate
+        the ticket supplied by the browser.
+
+        If validation is successful, the server must generate a Matrix login
+        token. It must then respond with an HTTP redirect to the URI given in
+        the ``redirectUrl`` parameter, adding a ``loginToken`` query parameter
+        giving the generated token.
+
+        If validation is unsuccessful, the server should respond with a ``401
+        Unauthorized`` error, the body of which will be displayed to the user.
+      operationId: loginByCASTicket
+      parameters:
+        - in: query
+          type: string
+          name: redirectUrl
+          description: |-
+            The ``redirectUrl`` originally provided by the client to
+            |/login/cas/redirect|_.
+          required: true
+        - in: query
+          type: string
+          name: ticket
+          description: |-
+            CAS authentication ticket.
+          required: true
+      responses:
+        302:
+          description: A redirect to the Matrix client.
+          headers:
+            Location:
+              type: "string"
+              x-example: |-
+                 https://client.example.com/?q=p&loginToken=secrettoken
+        401:
+          description: The server was unable to validate the CAS ticket.

api/client-server/content-repo.yaml

@@ -0,0 +1,271 @@
+# 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
+  - http
+basePath: /_matrix/media/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+  - "*/*"
+produces:
+  - application/json
+  - "*/*"
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/upload":
+    post:
+      summary: Upload some content to the content repository.
+      operationId: uploadContent
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      parameters:
+        - in: header
+          name: Content-Type
+          type: string
+          description: The content type of the file being uploaded
+          x-example: "Content-Type: audio/mpeg"
+        - in: query
+          type: string
+          x-example: "War and Peace.pdf"
+          name: filename
+          description: The name of the file being uploaded
+        - in: body
+          name: "<content>"
+          description: The content to be uploaded.
+          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"
+              }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media
+  "/download/{serverName}/{mediaId}":
+    get:
+      summary: "Download content from the content repository."
+      operationId: getContent
+      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
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media
+  "/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      summary: "Download content from the content repository as a given filename."
+      operationId: getContentOverrideName
+      produces: ["*/*"]
+      parameters:
+        - in: path
+          type: string
+          name: serverName
+          x-example: matrix.org
+          required: true
+          description: |
+            The server name from the ``mxc://`` URI (the authoritory component)
+        - in: path
+          type: string
+          name: mediaId
+          x-example: ascERGshawAWawugaAcauga
+          required: true
+          description: |
+            The media ID from the ``mxc://`` URI (the path component)
+        - in: path
+          type: string
+          name: fileName
+          x-example: filename.jpg
+          required: true
+          description: |
+            The filename to give in the Content-Disposition
+      responses:
+        200:
+          description: "The content that was previously uploaded."
+          headers:
+            Content-Type:
+              description: "The content type of the file that was previously uploaded."
+              type: "string"
+            Content-Disposition:
+              description: "The name of file given in the request"
+              type: "string"
+          schema:
+            type: file
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media
+  "/thumbnail/{serverName}/{mediaId}":
+    get:
+      summary: "Download a thumbnail of the content from the content repository."
+      operationId: getContentThumbnail
+      produces: ["image/jpeg", "image/png"]
+      parameters:
+        - in: path
+          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
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media
+  "/preview_url":
+    get:
+      summary: "Get information about a URL for a client"
+      operationId: getUrlPreview
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          x-example: "https://matrix.org"
+          name: url
+          description: "The URL to get a preview of"
+          required: true
+        - in: query
+          type: number
+          x-example: 1510610716656
+          name: ts
+          description: |-
+            The preferred point in time to return a preview for. The server may
+            return a newer version if it does not have the requested version
+            available.
+      responses:
+        200:
+          description: |-
+            The OpenGraph data for the URL, which may be empty. Some values are
+            replaced with matrix equivalents if they are provided in the response.
+            The differences from the OpenGraph protocol are described here.
+          schema:
+            type: object
+            properties:
+              "matrix:image:size":
+                type: number
+                description: |-
+                  The byte-size of the image. Omitted if there is no image attached.
+              "og:image":
+                type: string
+                description: |-
+                  An MXC URI to the image. Ommitted if there is no image.
+          examples:
+            application/json: {
+                "og:title": "Matrix Blog Post",
+                "og:description": "This is a really cool blog post from matrix.org",
+                "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
+                "og:image:type": "image/png",
+                "og:image:height": 48,
+                "og:image:width": 48,
+                "matrix:image:size": 102400
+              }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Media

api/client-server/create_room.yaml

@@ -0,0 +1,215 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Creation API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/createRoom":
+    post:
+      summary: Create a new room
+      description: |-
+        Create a new room with various configuration options.
+
+        The server MUST apply the normal state resolution rules when creating
+        the new room, including checking power levels for each event. It MUST
+        apply the events implied by the request in the following order:
+
+        0. A default ``m.room.power_levels`` event, giving the room creator
+           (and not other members) permission to send state events.
+        
+        1. Events set by ``presets``.
+
+        2. Events listed in ``initial_state``, in the order that they are
+           listed.
+
+        3. Events implied by ``name`` and ``topic``.
+
+        4. Invite events implied by ``invite`` and ``invite_3pid``.
+
+      operationId: createRoom
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          description: The desired room configuration.
+          schema:
+            type: object
+            example: {
+                "preset": "public_chat",
+                "room_alias_name": "thepub",
+                "name": "The Grand Duke Pub",
+                "topic": "All about happy hour",
+                "creation_content": {
+                    "m.federate": false
+                }
+              }
+            properties:
+              visibility:
+                type: string
+                enum: ["public", "private"]
+                description: |-
+                  A ``public`` visibility indicates that the room will be shown
+                  in the published room list. A ``private`` visibility will hide
+                  the room from the published room list. Rooms default to
+                  ``private`` visibility if this key is not included. NB: This
+                  should not be confused with ``join_rules`` which also uses the
+                  word ``public``.
+              room_alias_name:
+                type: string
+                description: |-
+                  The desired room alias **local part**. If this is included, a
+                  room alias will be created and mapped to the newly created
+                  room. The alias will belong on the *same* homeserver which
+                  created the room. For example, if this was set to "foo" and
+                  sent to the homeserver "example.com" the complete room alias
+                  would be ``#foo:example.com``.
+              name:
+                type: string
+                description: |-
+                  If this is included, an ``m.room.name`` event will be sent
+                  into the room to indicate the name of the room. See Room
+                  Events for more information on ``m.room.name``.
+              topic:
+                type: string
+                description: |-
+                  If this is included, an ``m.room.topic`` event will be sent
+                  into the room to indicate the topic for the room. See Room
+                  Events for more information on ``m.room.topic``.
+              invite:
+                type: array
+                description: |-
+                  A list of user IDs to invite to the room. This will tell the
+                  server to invite everyone in the list to the newly created room.
+                items:
+                  type: string
+              invite_3pid:
+                type: array
+                description: |-
+                  A list of objects representing third party IDs to invite into
+                  the room.
+                items:
+                  type: object
+                  title: Invite3pid
+                  properties:
+                    id_server:
+                      type: string
+                      description: The hostname+port of the identity server which should be used for third party identifier lookups.
+                    medium:
+                      type: string
+                      # TODO: Link to identity service spec when it eixsts
+                      description: The kind of address being passed in the address field, for example ``email``.
+                    address:
+                      type: string
+                      description: The invitee's third party identifier.
+                  required: ["id_server", "medium", "address"]
+              creation_content:
+                title: CreationContent
+                type: object
+                description: |-
+                  Extra keys to be added to the content of the ``m.room.create``.
+                  The server will clobber the following keys: ``creator``. Future
+                  versions of the specification may allow the server to clobber
+                  other keys.
+              initial_state:
+                type: array
+                description: |-
+                  A list of state events to set in the new room. This allows
+                  the user to override the default state events set in the new
+                  room. The expected format of the state events are an object
+                  with type, state_key and content keys set.
+
+                  Takes precedence over events set by ``presets``, but gets
+                  overriden by ``name`` and ``topic`` keys.
+                items:
+                  type: object
+                  title: StateEvent
+                  properties:
+                    type:
+                      type: string
+                    state_key:
+                      type: string
+                    content:
+                      type: string
+              preset:
+                type: string
+                enum: ["private_chat", "public_chat", "trusted_private_chat"]
+                description: |-
+                  Convenience parameter for setting various default state events
+                  based on a preset. Must be either:
+
+                  ``private_chat`` =>
+                    ``join_rules`` is set to ``invite``.
+                    ``history_visibility`` is set to ``shared``.
+
+                  ``trusted_private_chat`` =>
+                      ``join_rules`` is set to ``invite``.
+                      ``history_visibility`` is set to ``shared``.
+                      All invitees are given the same power level as the room creator.
+
+                  ``public_chat``: =>
+                      ``join_rules`` is set to ``public``.
+                      ``history_visibility`` is set to ``shared``.
+              is_direct:
+                type: boolean
+                description: |-
+                  This flag makes the server set the ``is_direct`` flag on the
+                  ``m.room.member`` events sent to the users in ``invite`` and
+                  ``invite_3pid``. See `Direct Messaging`_ for more information.
+      responses:
+        200:
+          description: Information about the newly created room.
+          schema:
+            type: object
+            description: Information about the newly created room.
+            properties:
+              room_id:
+                type: string
+                description: |-
+                  The created room's ID.
+          examples:
+            application/json: {
+                "room_id": "!sefiuhWgwghwWgh:example.com"
+              }
+        400:
+          description: |-
+
+            The request is invalid. A meaningful ``errcode`` and description
+            error text will be returned. Example reasons for rejection include:
+
+            - The request body is malformed (``errcode`` set to ``M_BAD_JSON``
+              or ``M_NOT_JSON``).
+
+            - The room alias specified is already taken (``errcode`` set to
+              ``M_ROOM_IN_USE``).
+
+            - The initial state implied by the parameters to the request is
+              invalid: for example, the user's ``power_level`` is set below
+              that necessary to set the room name (``errcode`` set to
+              ``M_INVALID_ROOM_STATE``).
+
+      tags:
+        - Room creation

api/client-server/definitions/auth_data.yaml

@@ -17,17 +17,16 @@ description: |-
 type: object
 properties:
   type:
-    description: |-
-      The authentication type that the client is attempting to complete.
-      May be omitted if `session` is given, and the client is reissuing a
-      request which it believes has been completed out-of-band (for example,
-      via the [fallback mechanism](/client-server-api/#fallback)).
+    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"

api/client-server/definitions/auth_response.yaml

@@ -18,10 +18,10 @@ 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
-      title: Flow information
       properties:
         stages:
           description: |-

api/client-server/definitions/device_keys.yaml

@@ -33,12 +33,12 @@ properties:
       type: string
     description: |-
       The encryption algorithms supported by this device.
-    example: ["m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2"]
+    example: ["m.olm.curve25519-aes-sha256", "m.megolm.v1.aes-sha"]
   keys:
     type: object
     description: |-
        Public identity keys. The names of the properties should be in the
-       format `<algorithm>:<device_id>`. The keys themselves should be
+       format ``<algorithm>:<device_id>``. The keys themselves should be
        encoded as specified by the key algorithm.
     additionalProperties:
        type: string
@@ -47,18 +47,16 @@ properties:
       "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
   signatures:
     type: object
-    title: Signatures
     description: |-
        Signatures for the device key object. A map from user ID, to a map from
-       `<algorithm>:<device_id>` to the signature.
+       ``<algorithm>:<device_id>`` to the signature.
 
-       The signature is calculated using the process described at [Signing JSON](/appendices/#signing-json).
-    patternProperties:
-      "^@":
-        x-pattern-format: mx-user-id
-        type: object
-        additionalProperties:
-          type: string
+       The signature is calculated using the process described at `Signing
+       JSON`_.
+    additionalProperties:
+      type: object
+      additionalProperties:
+        type: string
     example:
       "@alice:example.com":
         "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"

api/client-server/definitions/error.yaml

@@ -12,15 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-title: Error
 description: A Matrix-level Error
 properties:
   errcode:
     type: string
     description: An error code.
-    example: M_UNKNOWN
   error:
     type: string
     description: A human-readable error message.
-    example: An unknown error occurred
-required: ["errcode"]
+required: ["errcode"]

api/client-server/definitions/event-schemas

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

api/client-server/definitions/event.yaml

@@ -0,0 +1,65 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+properties:
+  event_id:
+    description: The ID of this event, if applicable.
+    type: string
+  content:
+    description: The content of this event. The fields in this object will vary depending
+      on the type of event.
+    title: EventContent
+    type: object
+  origin_server_ts:
+    description: Timestamp in milliseconds on originating homeserver when this event
+      was sent.
+    format: int64
+    type: integer
+  sender:
+    description: The MXID of the user who sent this event.
+    type: string
+  state_key:
+    description: Optional. This key will only be present for state events. A unique
+      key which defines the overwriting semantics for this piece of room state.
+    type: string
+  type:
+    description: The type of event.
+    type: string
+  unsigned:
+    description: Information about this event which was not sent by the originating
+      homeserver
+    properties:
+      age:
+        description: Time in milliseconds since the event was sent.
+        format: int64
+        type: integer
+      prev_content:
+        description: Optional. The previous ``content`` for this state. This will
+          be present only for state events appearing in the ``timeline``. If this
+          is not a state event, or there is no previous content, this key will be
+          missing.
+        title: EventContent
+        type: object
+      transaction_id:
+        description: Optional. The transaction ID set when this message was sent.
+          This key will only be present for message events sent by the device calling
+          this API.
+        type: string
+      redacted_because:
+        description: Optional. The event that redacted this event, if any.
+        title: Event
+        type: object
+    title: Unsigned
+    type: object
+title: Event
+type: object

api/client-server/definitions/event_batch.yaml

@@ -1,5 +1,4 @@
 # Copyright 2016 OpenMarket Ltd
-# Copyright 2018 New Vector Ltd
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,9 +13,10 @@
 # limitations under the License.
 properties:
   events:
-    description: List of events.
+    description: List of events
     items:
-      $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
+      allOf:
+      - $ref: event.yaml
+      type: object
     type: array
 type: object
-title: EventBatch

api/client-server/definitions/event_filter.yaml

@@ -11,26 +11,22 @@
 # 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: EventFilter
+title: Filter
 properties:
   limit:
-    description: |
-      The maximum number of events to return, must be an integer greater than 0.
-
-      Servers should apply a default value, and impose a maximum value to avoid
-      resource exhaustion.
+    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.
+      ``'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
+      in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string
@@ -43,7 +39,7 @@ properties:
     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
+      event types are included. A ``'*'`` can be used as a wildcard to match any sequence
       of characters.
     items:
       type: string

api/client-server/definitions/push_condition.yaml

@@ -0,0 +1,45 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+title: PushCondition
+type: object
+properties:
+  kind:
+    enum:
+    - event_match
+    - contains_display_name
+    - room_member_count
+    type: string
+  key:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The dot-separated field of the
+      event to match.
+    x-example: content.body
+  pattern:
+    type: string
+    description: |-
+      Required for ``event_match`` conditions. The glob-style pattern to
+      match against. Patterns with no special glob characters should be
+      treated as having asterisks prepended and appended when testing the
+      condition.
+  is:
+    type: string
+    description: |-
+      Required for ``room_member_count`` conditions. A decimal integer
+      optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches
+      rooms where the member count is strictly less than the given number and
+      so forth. If no prefix is present, this parameter defaults to ==.
+required:
+  - kind

api/client-server/definitions/push_rule.yaml

@@ -17,7 +17,9 @@ type: object
 properties:
   actions:
     items:
-      type: ["string", "object"]
+      type:
+      - object
+      - string
     type: array
     description: |-
       The actions to perform when this rule is matched.
@@ -36,16 +38,17 @@ properties:
   conditions:
     type: array
     items:
-      $ref: push_condition.yaml
+      allOf:
+      - $ref: push_condition.yaml
     description: |-
       The conditions that must hold true for an event in order for a rule to be
       applied to an event. A rule with no conditions always matches. Only
-      applicable to `underride` and `override` rules.
+      applicable to ``underride`` and ``override`` rules.
   pattern:
     type: string
     description: |-
-      The [glob-style pattern](/appendices#glob-style-matching) to match against.
-      Only applicable to `content` rules.
+      The glob-style pattern to match against.  Only applicable to ``content``
+      rules.
 required:
   - actions
   - default

api/client-server/definitions/push_ruleset.yaml

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

api/client-server/definitions/room_event_filter.yaml

@@ -1,4 +1,4 @@
-# Copyright 2023 The Matrix.org Foundation C.I.C.
+# 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.
@@ -11,23 +11,25 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
-type: object
-title: m.mentions
-description: |-
-  Describes whether the event mentions other users or the room. This is contained
-  within the event's `content` alongside other fields for the relevant event type.
-example: {
-    "user_ids": ["@alice:example.org"]
-}
+allOf:
+- $ref: event_filter.yaml
+title: RoomEventFilter
 properties:
-  user_ids:
-    type: array
+  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
-    description: A list of Matrix IDs of mentioned users.
-  room:
+    type: array
+  rooms:
+    description: A list of room IDs to include. If this list is absent then all rooms
+      are included.
+    items:
+      type: string
+    type: array
+  contains_url:
     type: boolean
-    description: |-
-      A boolean set to `true` to mention the room, for an `@room` notification.
-      (`room` should otherwise not be included on the event.)
+    description: If ``true``, includes only events with a url key in their content. If
+      ``false``, excludes those events.
+type: object

api/client-server/definitions/security.yaml

@@ -1,4 +1,4 @@
-# Copyright 2018 New Vector Ltd
+# 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.
@@ -11,7 +11,8 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-type: array
-description: List of matched third-party locations.
-items:
-  $ref: location.yaml
+accessToken:
+  type: apiKey
+  description: The access_token returned by a call to ``/login`` or ``/register``
+  name: access_token
+  in: query

api/client-server/definitions/sync_filter.yaml

@@ -11,20 +11,19 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-type: object
-title: Filter
 properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
-      fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
-      to include. So ['content.body'] will include the 'body' field of the 'content' object.
-      A server may include more fields than were requested.
+      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 received
+      a format suitable for clients. 'federation' will return the raw event as receieved
       over federation. The default is 'client'.
     enum:
     - client
@@ -41,34 +40,31 @@ properties:
   room:
     title: RoomFilter
     description: Filters to be applied to room data.
-    type: object
     properties:
       not_rooms:
         description: A list of room IDs to exclude. If this list is absent then no rooms
-          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`
+          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`
+          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 ephemeral events to include for rooms. These are the
-          events that appear in the `ephemeral` property in the `/sync`
-          response.
+        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:
-        type: object
         allOf:
         - $ref: room_event_filter.yaml
         description: The state events to include for rooms.
@@ -80,3 +76,5 @@ properties:
         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,4 +1,4 @@
-# Copyright 2025 The Matrix.org Foundation C.I.C.
+# 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.
@@ -11,13 +11,15 @@
 # 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: |-
-  The room_id field of PDUs for room version 12 and beyond.
+allOf:
+- $ref: event_batch.yaml
 properties:
-  room_id:
+  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
-    description: Room identifier. Omitted from `m.room.create` events.
-    example: "!Nhcu5BS-UMnFX7hBVfVSoXiD7OgH6iRT-xyIuqDnpYQ"
-required:
-  - room_id
+type: object

api/client-server/device_management.yaml

@@ -0,0 +1,179 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server device management API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/devices":
+    get:
+      summary: List registered devices for the current user
+      description: |-
+        Gets information about all devices for the current user.
+      operationId: getDevices
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            properties:
+              devices:
+                type: array
+                description: A list of all registered devices for this user.
+                items:
+                  type: object
+                  allOf:
+                    - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: {
+                "devices": [
+                  {
+                    "device_id": "QBUAZIFURK",
+                    "display_name": "android",
+                    "last_seen_ip": "1.2.3.4",
+                    "last_seen_ts": 1474491775024
+                  }
+                ]
+              }
+      tags:
+        - Device management
+  "/devices/{deviceId}":
+    get:
+      summary: Get a single device
+      description: |-
+        Gets information on a single device, by device id.
+      operationId: getDevice
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to retrieve.
+          required: true
+          x-example: "QBUAZIFURK"
+      responses:
+        200:
+          description: Device information
+          schema:
+            type: object
+            allOf:
+               - $ref: "definitions/client_device.yaml"
+          examples:
+            application/json: {
+                "device_id": "QBUAZIFURK",
+                "display_name": "android",
+                "last_seen_ip": "1.2.3.4",
+                "last_seen_ts": 1474491775024
+              }
+        404:
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    put:
+      summary: Update a device
+      description: |-
+        Updates the metadata on the given device.
+      operationId: updateDevice
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to update.
+          required: true
+          x-example: "QBUAZIFURK"
+        - in: body
+          name: body
+          required: true
+          description: New information for the device.
+          schema:
+            type: object
+            properties:
+              display_name:
+                type: string
+                description: |-
+                    The new display name for this device. If not given, the
+                    display name is unchanged.
+                example: My other phone
+      responses:
+        200:
+          description: The device was successfully updated.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object  # empty json object
+        404:
+          description: The current user has no device with the given ID.
+      tags:
+        - Device management
+    delete:
+      summary: Delete a device
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Deletes the given device, and invalidates any access token assoicated with it.
+      operationId: deleteDevice
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: deviceId
+          description: The device to delete.
+          required: true
+          x-example: "QBUAZIFURK"
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+      responses:
+        200:
+          description: |-
+            The device was successfully removed, or had been removed
+            previously.
+          schema:
+            type: object
+          examples:
+            application/json: {
+              }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+      tags:
+        - Device management

api/client-server/directory.yaml

@@ -0,0 +1,148 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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.
+      operationId: setRoomAlias
+      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.
+
+      operationId: getRoomIdByAlias
+      parameters:
+        - in: path
+          type: string
+          name: roomAlias
+          description: The room alias.
+          required: true
+          x-example: "#monkeys:matrix.org"
+      responses:
+        200:
+          description: The room ID and other information for this alias.
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID for this room alias.
+              servers:
+                type: array
+                description: A list of servers that are aware of this room alias.
+                items:
+                  type: string
+                  description: A server which is aware of this room alias.
+          examples:
+            application/json: {
+                "room_id": "!abnjk1jdasj98:capuchins.com",
+                "servers": [
+                  "capuchins.com",
+                  "matrix.org",
+                  "another.com"
+                ]
+              }
+        404:
+          description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: {
+                "errcode": "M_NOT_FOUND",
+                "error": "Room alias #monkeys:matrix.org not found."
+              }
+      tags:
+        - Room directory
+    delete:
+      summary: Remove a mapping of room alias to room ID.
+      description: |-
+        Remove a mapping of room alias to room ID.
+
+        Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.
+      operationId: deleteRoomAlias
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomAlias
+          description: The room alias to remove.
+          required: true
+          x-example: "#monkeys:matrix.org"
+      responses:
+        200:
+          description: The mapping was deleted.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+      tags:
+        - Room directory

api/client-server/event_context.yaml

@@ -0,0 +1,165 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Event Context API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/context/{eventId}":
+    get:
+      summary: Get events and state around the specified event.
+      description: |-
+        This API returns a number of events that happened just before and
+        after the specified event. This allows clients to get the context
+        surrounding an event.
+      operationId: getEventContext
+      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

@@ -0,0 +1,155 @@
+# 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.
+      operationId: defineFilter
+      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
+      operationId: getFilter
+      security:
+        - accessToken: []
+      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"
+        404:
+          description: "Unknown filter."
+      tags:
+        - Room participation

api/client-server/inviting.yaml

@@ -0,0 +1,101 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Joining API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  # With an extra " " to disambiguate from the 3pid invite endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
+  "/rooms/{roomId}/invite ":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        .. _invite-by-user-id-endpoint:
+
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API requires that the inviter knows the Matrix
+        identifier of the invitee. The other is documented in the*
+        `third party invites section`_.
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the user was invited to the room, the homeserver will append a
+        ``m.room.member`` event to the room.
+
+        .. _third party invites section: `invite-by-third-party-id-endpoint`_
+      operationId: inviteUser
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            example: {
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+            properties:
+              user_id:
+                type: string
+                description: The fully qualified user ID of the invitee.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been invited to join the room.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - The inviter is not currently in the room.
+            - The inviter's power level is insufficient to invite users to the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/joining.yaml

@@ -0,0 +1,214 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Inviting API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/join":
+    post:
+      summary: Start the requesting user participating in a particular room.
+      description: |-
+        *Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*
+
+        This API starts a user participating in a particular room, if that user
+        is allowed to participate in that room. After this call, the client is
+        allowed to see all current state events in the room, and all subsequent
+        events associated with the room until the user leaves the room.
+
+        After a user has joined a room, the room will appear as an entry in the
+        response of the |/initialSync|_ and |/sync|_ APIs.
+
+        If a ``third_party_signed`` was supplied, the homeserver must verify
+        that it matches a pending ``m.room.third_party_invite`` event in the
+        room, and perform key validity checking if required by the event.
+      operationId: joinRoomById
+      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.
+      operationId: joinRoom
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomIdOrAlias
+          description: The room identifier or alias to join.
+          required: true
+          x-example: "#monkeys:matrix.org"
+        - in: body
+          name: third_party_signed
+          schema:
+            type: object
+            example: {
+                "third_party_signed": {
+                  "signed": {
+                    "sender": "@cat:the.hat",
+                    "mxid": "@green:eggs.ham",
+                    "token": "random8nonce",
+                    "signatures": {
+                      "horton.hears": {
+                        "ed25519:0": "some9signature"
+                      }
+                    }
+                  }
+                }
+              }
+            properties:
+              third_party_signed:
+                type: object
+                title: ThirdPartySigned
+                description: A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.
+                properties:
+                  signed:
+                    type: object
+                    title: Signed
+                    properties:
+                      sender:
+                        type: string
+                        description: The Matrix ID of the user who issued the invite.
+                      mxid:
+                        type: string
+                        description: The Matrix ID of the invitee.
+                      token:
+                        type: string
+                        description: The state key of the m.third_party_invite event.
+                      signatures:
+                        type: object
+                        description: A signatures object containing a signature of the entire signed object.
+                        title: Signatures
+                    required: ["sender", "mxid", "token", "signatures"]
+                required: ["signed"]
+      responses:
+        200:
+          description: |-
+            The room has been joined.
+
+            The joined room ID must be returned in the ``room_id`` field.
+          examples:
+            application/json: {
+              "room_id": "!d41d8cd:matrix.org"}
+          schema:
+            type: object
+        403:
+          description: |-
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+
+            - The room is invite-only and the user was not invited.
+            - The user has been banned from the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Room membership

api/client-server/keys.yaml

@@ -0,0 +1,340 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Client Config API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/keys/upload":
+    post:
+      summary: Upload end-to-end encryption keys.
+      description: |-
+        Publishes end-to-end encryption keys for the device.
+      operationId: uploadKeys
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: keys
+          description: |-
+            The keys to be published
+          schema:
+            type: object
+            properties:
+              device_keys:
+                description: |-
+                  Identity keys for the device. May be absent if no new
+                  identity keys are required.
+                allOf:
+                  - $ref: definitions/device_keys.yaml
+              one_time_keys:
+                type: object
+                description: |-
+                  One-time public keys for "pre-key" messages.  The names of
+                  the properties should be in the format
+                  ``<algorithm>:<key_id>``. The format of the key is determined
+                  by the key algorithm.
+
+                  May be absent if no new one-time keys are required.
+                additionalProperties:
+                  type:
+                    - string
+                    - object
+                example:
+                  "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8"
+                  signed_curve25519:AAAAHg:
+                    key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
+                    signatures:
+                      "@alice:example.com":
+                        ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+                  signed_curve25519:AAAAHQ:
+                    key: "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw"
+                    signatures:
+                      "@alice:example.com":
+                        ed25519:JLAFKJWSCS: "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
+      responses:
+        200:
+          description:
+            The provided keys were sucessfully uploaded.
+          schema:
+            type: object
+            properties:
+              one_time_key_counts:
+                type: object
+                additionalProperties:
+                  type: integer
+                description: |-
+                  For each key algorithm, the number of unclaimed one-time keys
+                  of that type currently held on the server for this device.
+                example:
+                  curve25519: 10
+                  signed_curve25519: 20
+            required:
+              - one_time_key_counts
+
+      tags:
+        - End-to-end encryption
+  "/keys/query":
+    post:
+      summary: Download device identity keys.
+      description: |-
+        Returns the current devices and identity keys for the given users.
+      operationId: queryKeys
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: query
+          description: |-
+            Query defining the keys to be downloaded
+          schema:
+            type: object
+            properties:
+              timeout:
+                type: integer
+                description: |-
+                  The time (in milliseconds) to wait when downloading keys from
+                  remote servers. 10 seconds is the recommended default.
+                example: 10000
+              device_keys:
+                type: object
+                description: |-
+                  The keys to be downloaded. A map from user ID, to a list of
+                  device IDs, or to an empty list to indicate all devices for the
+                  corresponding user.
+                additionalProperties:
+                  type: array
+                  items:
+                    type: string
+                    description: "device ID"
+                example:
+                  "@alice:example.com": []
+            required:
+              - device_keys
+
+      responses:
+        200:
+          description:
+            The device information
+          schema:
+            type: object
+            properties:
+              failures:
+                type: object
+                description: |-
+                  If any remote homeservers could not be reached, they are
+                  recorded here. The names of the properties are the names of
+                  the unreachable servers.
+
+                  If the homeserver could be reached, but the user or device
+                  was unknown, no failure is recorded. Instead, the corresponding
+                  user or device is missing from the ``device_keys`` result.
+                additionalProperties:
+                  type: object
+                example: {}
+              device_keys:
+                type: object
+                description: |-
+                  Information on the queried devices. A map from user ID, to a
+                  map from device ID to device information.  For each device,
+                  the information returned will be the same as uploaded via
+                  ``/keys/upload``, with the addition of an ``unsigned``
+                  property.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    allOf:
+                      - $ref: definitions/device_keys.yaml
+                    properties:
+                      unsigned:
+                        title: UnsignedDeviceInfo
+                        type: object
+                        description: |-
+                          Additional data added to the device key information
+                          by intermediate servers, and not covered by the
+                          signatures.
+                        properties:
+                          device_display_name:
+                            type: string
+                            description:
+                              The display name which the user set on the device.
+                example:
+                  "@alice:example.com":
+                    JLAFKJWSCS: {
+                      "user_id": "@alice:example.com",
+                      "device_id": "JLAFKJWSCS",
+                      "algorithms": [
+                        "m.olm.curve25519-aes-sha256",
+                        "m.megolm.v1.aes-sha"
+                      ],
+                      "keys": {
+                        "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
+                        "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
+                      },
+                      "signatures": {
+                        "@alice:example.com": {
+                          "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
+                        }
+                      },      
+                      "unsigned": {
+                        "device_display_name": "Alice's mobile phone"
+                      }
+                    }
+         
+      tags:
+        - End-to-end encryption
+  "/keys/claim":
+    post:
+      summary: Claim one-time encryption keys.
+      description: |-
+        Claims one-time keys for use in pre-key messages.
+      operationId: claimKeys
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: query
+          description: |-
+            Query defining the keys to be claimed
+          schema:
+            type: object
+            properties:
+              timeout:
+                type: integer
+                description: |-
+                  The time (in milliseconds) to wait when downloading keys from
+                  remote servers. 10 seconds is the recommended default.
+                example: 10000
+              one_time_keys:
+                type: object
+                description: |-
+                  The keys to be claimed. A map from user ID, to a map from
+                  device ID to algorithm name.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type: string
+                    description: algorithm
+                    example: "signed_curve25519"
+                example:
+                  "@alice:example.com": { "JLAFKJWSCS": "curve25519" }
+            required:
+              - one_time_keys
+      responses:
+        200:
+          description:
+            The claimed keys
+          schema:
+            type: object
+            properties:
+              failures:
+                type: object
+                description: |-
+                  If any remote homeservers could not be reached, they are
+                  recorded here. The names of the properties are the names of
+                  the unreachable servers.
+                  
+                  If the homeserver could be reached, but the user or device
+                  was unknown, no failure is recorded. Instead, the corresponding
+                  user or device is missing from the ``one_time_keys`` result.
+                additionalProperties:
+                  type: object
+                example: {}
+              one_time_keys:
+                type: object
+                description: |-
+                  One-time keys for the queried devices. A map from user ID, to a
+                  map from ``<algorithm>:<key_id>`` to the key object.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type:
+                      - string
+                      - object
+                example:
+                  "@alice:example.com":
+                    JLAFKJWSCS:
+                      signed_curve25519:AAAAHg:
+                        key: "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs"
+                        signatures:
+                          "@alice:example.com":
+                            ed25519:JLAFKJWSCS: "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
+      tags:
+        - End-to-end encryption
+  "/keys/changes":
+    get:
+      summary: Query users with recent device key updates.
+      description: |-
+        Gets a list of users who have updated their device identity keys since a
+        previous sync token.
+
+        The server should include in the results any users who:
+
+        * currently share a room with the calling user (ie, both users have
+          membership state ``join``); *and*
+        * added new device identity keys or removed an existing device with
+          identity keys, between ``from`` and ``to``.
+      operationId: getKeysChanges
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          name: from
+          type: string
+          description: |-
+             The desired start point of the list. Should be the ``next_batch`` field
+             from a response to an earlier call to |/sync|. Users who have not
+             uploaded new device identity keys since this point, nor deleted
+             existing devices with identity keys since then, will be excluded
+             from the results.
+          required: true
+          x-example: "s72594_4483_1934"
+        - in: query
+          name: to
+          type: string
+          description: |-
+             The desired end point of the list. Should be the ``next_batch``
+             field from a recent call to |/sync| - typically the most recent
+             such call. This may be used by the server as a hint to check its
+             caches are up to date.
+          required: true
+          x-example: "s75689_5632_2435"
+      responses:
+        200:
+          description:
+            The list of users who updated their devices.
+          schema:
+            type: object
+            properties:
+              changes:
+                type: array
+                items:
+                  type: string
+                description: |-
+                  The Matrix User IDs of all users who updated their device
+                  identity keys.
+                example: ["@alice:example.com", "@bob:example.org"]
+      tags:
+        - End-to-end encryption

api/client-server/kicking.yaml

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

api/client-server/leaving.yaml

@@ -0,0 +1,107 @@
+# 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.
+      operationId: leaveRoom
+      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.
+      operationId: forgetRoom
+      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_joined_rooms.yaml

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

api/client-server/list_public_rooms.yaml

@@ -0,0 +1,301 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Creation API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/publicRooms":
+    get:
+      summary: Lists the public rooms on the server.
+      description: |-
+        Lists the public rooms on the server.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      operationId: getPublicRooms
+      parameters:
+        - in: query
+          name: limit
+          type: number
+          description: |-
+            Limit the number of results returned.
+        - in: query
+          name: since
+          type: string
+          description: |-
+            A pagination token from a previous request, allowing clients to
+            get the next (or previous) batch of rooms.
+            The direction of pagination is specified solely by which token
+            is supplied, rather than via an explicit flag.
+        - in: query
+          name: server
+          type: string
+          description: |-
+            The server to fetch the public room lists from. Defaults to the
+            local server.
+      responses:
+        200:
+          description: A list of the rooms on the server.
+          schema:
+            type: object
+            description: A list of the rooms on the server.
+            required: ["chunk"]
+            properties:
+              chunk:
+                title: "PublicRoomsChunks"
+                type: array
+                description: |-
+                  A paginated chunk of public rooms.
+                items:
+                  type: object
+                  title: "PublicRoomsChunk"
+                  required:
+                    - room_id
+                    - num_joined_members
+                    - world_readable
+                    - guest_can_join
+                  properties:
+                    aliases:
+                      type: array
+                      description: |-
+                        Aliases of the room. May be empty.
+                      items:
+                        type: string
+                    canonical_alias:
+                      type: string
+                      description: |-
+                        The canonical alias of the room, if any.
+                    name:
+                      type: string
+                      description: |-
+                        The name of the room, if any.
+                    num_joined_members:
+                      type: number
+                      description: |-
+                        The number of members joined to the room.
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    topic:
+                      type: string
+                      description: |-
+                        The topic of the room, if any.
+                    world_readable:
+                      type: boolean
+                      description: |-
+                        Whether the room may be viewed by guest users without joining.
+                    guest_can_join:
+                      type: boolean
+                      description: |-
+                        Whether guest users may join the room and participate in it.
+                        If they can, they will be subject to ordinary power level
+                        rules like any other user.
+                    avatar_url:
+                      type: string
+                      description: The URL for the room's avatar, if one is set.
+              next_batch:
+                type: string
+                description: |-
+                  A pagination token for the response. The absence of this token
+                  means there are no more results to fetch and the client should
+                  stop paginating.
+              prev_batch:
+                type: string
+                description: |-
+                  A pagination token that allows fetching previous results. The
+                  absence of this token means there are no results before this
+                  batch, i.e. this is the first batch.
+              total_room_count_estimate:
+                type: number
+                description: |-
+                   An estimate on the total number of public rooms, if the
+                   server has an estimate.
+          examples:
+            application/json: {
+                "chunk": [
+                  {
+                    "aliases": ["#murrays:cheese.bar"],
+                    "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
+                    "guest_can_join": false,
+                    "name": "CHEESE",
+                    "num_joined_members": 37,
+                    "room_id": "!ol19s:bleecker.street",
+                    "topic": "Tasty tasty cheese",
+                    "world_readable": true
+                  }
+                ],
+                "next_batch": "p190q",
+                "prev_batch": "p1902",
+                "total_room_count_estimate": 115
+              }
+      tags:
+        - Room discovery
+    post:
+      summary: Lists the public rooms on the server with optional filter.
+      description: |-
+        Lists the public rooms on the server, with optional filter.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      operationId: queryPublicRooms
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          name: server
+          type: string
+          description: |-
+            The server to fetch the public room lists from. Defaults to the
+            local server.
+        - in: body
+          name: body
+          required: true
+          description: |-
+            Options for which rooms to return.
+          schema:
+            type: object
+            properties:
+              limit:
+                type: number
+                description: |-
+                  Limit the number of results returned.
+              since:
+                type: string
+                description: |-
+                  A pagination token from a previous request, allowing clients
+                  to get the next (or previous) batch of rooms.  The direction
+                  of pagination is specified solely by which token is supplied,
+                  rather than via an explicit flag.
+              filter:
+                type: object
+                title: "Filter"
+                description: |-
+                  Filter to apply to the results.
+                properties:
+                    generic_search_term:
+                      type: string
+                      description: |-
+                        A string to search for in the room metadata, e.g. name,
+                        topic, canonical alias etc. (Optional).
+            example: {
+              "limit": 10, "filter": {"generic_search_term": "foo"}}
+      responses:
+        200:
+          description: A list of the rooms on the server.
+          schema:
+            type: object
+            description: A list of the rooms on the server.
+            required: ["chunk"]
+            properties:
+              chunk:
+                title: "PublicRoomsChunks"
+                type: array
+                description: |-
+                  A paginated chunk of public rooms.
+                items:
+                  type: object
+                  title: "PublicRoomsChunk"
+                  required:
+                    - room_id
+                    - num_joined_members
+                    - world_readable
+                    - guest_can_join
+                  properties:
+                    aliases:
+                      type: array
+                      description: |-
+                        Aliases of the room. May be empty.
+                      items:
+                        type: string
+                    canonical_alias:
+                      type: string
+                      description: |-
+                        The canonical alias of the room, if any.
+                    name:
+                      type: string
+                      description: |-
+                        The name of the room, if any.
+                    num_joined_members:
+                      type: number
+                      description: |-
+                        The number of members joined to the room.
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    topic:
+                      type: string
+                      description: |-
+                        The topic of the room, if any.
+                    world_readable:
+                      type: boolean
+                      description: |-
+                        Whether the room may be viewed by guest users without joining.
+                    guest_can_join:
+                      type: boolean
+                      description: |-
+                        Whether guest users may join the room and participate in it.
+                        If they can, they will be subject to ordinary power level
+                        rules like any other user.
+                    avatar_url:
+                      type: string
+                      description: The URL for the room's avatar, if one is set.
+              next_batch:
+                type: string
+                description: |-
+                  A pagination token for the response. The absence of this token
+                  means there are no more results to fetch and the client should
+                  stop paginating.
+              prev_batch:
+                type: string
+                description: |-
+                  A pagination token that allows fetching previous results. The
+                  absence of this token means there are no results before this
+                  batch, i.e. this is the first batch.
+              total_room_count_estimate:
+                type: number
+                description: |-
+                   An estimate on the total number of public rooms, if the
+                   server has an estimate.
+          examples:
+            application/json: {
+                "chunk": [
+                  {
+                    "aliases": ["#murrays:cheese.bar"],
+                    "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
+                    "guest_can_join": false,
+                    "name": "CHEESE",
+                    "num_joined_members": 37,
+                    "room_id": "!ol19s:bleecker.street",
+                    "topic": "Tasty tasty cheese",
+                    "world_readable": true
+                  }
+                ],
+                "next_batch": "p190q",
+                "prev_batch": "p1902",
+                "total_room_count_estimate": 115
+              }
+      tags:
+        - Room discovery

api/client-server/login.yaml

@@ -0,0 +1,140 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Registration and Login API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/login":
+    post:
+      summary: Authenticates the user.
+      description: |-
+        Authenticates the user, and issues an access token they can
+        use to authorize themself in subsequent requests.
+
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        The returned access token must be associated with the ``device_id``
+        supplied by the client or generated by the server. The server may
+        invalidate any access token previously associated with that device. See
+        `Relationship between access tokens and devices`_.
+      operationId: login
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "type": "m.login.password",
+                "user": "cheeky_monkey",
+                "password": "ilovebananas",
+                "initial_device_display_name": "Jungle Phone"
+              }
+            properties:
+              type:
+                type: string
+                enum: ["m.login.password", "m.login.token"]
+                description: The login type being used.
+              user:
+                type: string
+                description: The fully qualified user ID or just local part of the user ID, to log in.
+              medium:
+                type: string
+                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.
+              address:
+                type: string
+                description: Third party identifier for the user.
+              password:
+                type: string
+                description: |-
+                  Required when ``type`` is ``m.login.password``. The user's
+                  password.
+              token:
+                type: string
+                description: |-
+                  Required when ``type`` is ``m.login.token``. The login token.
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
+            required: ["type"]
+
+      responses:
+        200:
+          description: The user has been authenticated.
+          examples:
+            application/json: {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The fully-qualified Matrix ID that has been registered.
+              access_token:
+                type: string
+                description: |-
+                  An access token for the account.
+                  This access token can then be used to authorize other requests.
+              home_server:
+                type: string
+                description: The hostname of the homeserver on which the account has been registered.
+              device_id:
+                type: string
+                description: |-
+                  ID of the logged-in device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+        400:
+          description: |-
+            Part of the request was invalid. For example, the login type may not be recognised.
+          examples:
+            application/json: {
+                  "errcode": "M_UNKNOWN",
+                  "error": "Bad login type."
+              }
+        403:
+          description: |-
+            The login attempt failed. For example, the password may have been incorrect.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN"}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - Session management

api/client-server/logout.yaml

@@ -0,0 +1,46 @@
+# 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.
+      operationId: logout
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The access token used in the request was succesfully invalidated.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - Session management

api/client-server/message_pagination.yaml

@@ -0,0 +1,160 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Rooms API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/messages":
+    get:
+      summary: Get a list of events for this room
+      description: |-
+        This API returns a list of message and state events for a room. It uses
+        pagination query parameters to paginate history in the room.
+      operationId: getRoomEvents
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get events from.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: query
+          type: string
+          name: from
+          description: |-
+            The token to start returning events from. This token can be obtained
+            from a ``prev_batch`` token returned for each room by the sync API,
+            or from a ``start`` or ``end`` token returned by a previous request
+            to this endpoint.
+          required: true
+          x-example: "s345_678_333"
+        - in: query
+          type: string
+          name: to
+          description: |-
+            The token to stop returning events at. This token can be obtained from
+            a ``prev_batch`` token returned for each room by the sync endpoint,
+            or from a ``start`` or ``end`` token returned by a previous request to
+            this endpoint.
+          required: false
+        - in: query
+          type: string
+          enum: ["b", "f"]
+          name: dir
+          description: |-
+            The direction to return events from.
+          required: true
+          x-example: "b"
+        - in: query
+          type: integer
+          name: limit
+          description: |-
+            The maximum number of events to return. Default: 10.
+          x-example: "3"
+        - in: query
+          type: string
+          name: filter
+          description: |-
+            A JSON RoomEventFilter to filter returned events with.
+          x-example: |-
+            {"contains_url":true}
+      responses:
+        200:
+          description: A list of messages with a new token to request more.
+          schema:
+            type: object
+            description: A list of messages with a new token to request more.
+            properties:
+              start:
+                type: string
+                description: |-
+                  The token the pagination starts from. If ``dir=b`` this will be
+                  the token supplied in ``from``.
+              end:
+                type: string
+                description: |-
+                  The token the pagination ends at. If ``dir=b`` this token should
+                  be used again to request even earlier events.
+              chunk:
+                type: array
+                description: |-
+                  A list of room events.
+                items:
+                  type: object
+                  title: RoomEvent
+          examples:
+            application/json: {
+                "start": "t47429-4392820_219380_26003_2265",
+                "end": "t47409-4357353_219380_26003_2265",
+                "chunk": [
+                  {
+                    "origin_server_ts": 1444812213737,
+                    "sender": "@alice:example.com",
+                    "event_id": "$1444812213350496Caaaa:example.com",
+                    "content": {
+                      "body": "hello world",
+                      "msgtype":"m.text"
+                    },
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.message",
+                    "age": 1042
+                  },
+                  {
+                    "origin_server_ts": 1444812194656 ,
+                    "sender": "@bob:example.com",
+                    "event_id": "$1444812213350496Cbbbb:example.com",
+                    "content": {
+                      "body": "the world is big",
+                      "msgtype":"m.text"
+                    },
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.message",
+                    "age": 20123
+                  },
+                  {
+                    "origin_server_ts": 1444812163990,
+                    "sender": "@bob:example.com",
+                    "event_id": "$1444812213350496Ccccc:example.com",
+                    "content": {
+                      "name": "New room name"
+                    },
+                    "prev_content": {
+                      "name": "Old room name"
+                    },
+                    "state_key": "",
+                    "room_id":"!Xq3620DUiqCaoxq:example.com",
+                    "type":"m.room.name",
+                    "age": 50789
+                  }
+                ]
+              }
+        403:
+          description: >
+            You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/notifications.yaml

@@ -0,0 +1,142 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Notifications API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/notifications":
+    get:
+      summary: Gets a list of events that the user has been notified about
+      description: |-
+        This API is used to paginate through the list of events that the
+        user has been, or would have been notified about.
+      operationId: getNotifications
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          name: from
+          description: Pagination token given to retrieve the next set of events.
+          required: false
+          x-example: "xxxxx"
+        - in: query
+          type: number
+          name: limit
+          description: Limit on the number of events to return in this request.
+          required: false
+          x-example: "20"
+        - in: query
+          name: only
+          type: string
+          description: |-
+            Allows basic filtering of events returned. Supply ``highlight``
+            to return only events where the notification had the highlight
+            tweak set.
+          required: false
+          x-example: "highlight"
+      responses:
+        200:
+          description: A batch of events is being returned
+          examples:
+            application/json: {
+                "next_token": "abcdef",
+                "notifications": [
+                  {
+                    "actions": [
+                      "notify"
+                    ],
+                    "profile_tag": "hcbvkzxhcvb",
+                    "read": true,
+                    "room_id": "!abcdefg:example.com",
+                    "ts": 1475508881945,
+                    "event": {
+                      "sender": "@alice:example.com",
+                      "type": "m.room.message",
+                      "age": 124524,
+                      "txn_id": "1234",
+                      "content": {
+                        "body": "I am a fish",
+                        "msgtype": "m.text"
+                      },
+                      "origin_server_ts": 1417731086797,
+                      "event_id": "$74686972643033:example.com"
+                    }
+                  }
+                ]
+              }
+          schema:
+            type: object
+            required: ["notifications"]
+            properties:
+              next_token:
+                type: string
+                description: |-
+                  The token to supply in the ``from`` param of the next
+                  ``/notifications`` request in order to request more
+                  events. If this is absent, there are no more results.
+              notifications:
+                type: array
+                items:
+                  type: object
+                  required: ["actions", "event", "read", "room_id", "ts"]
+                  title: Notification
+                  properties:
+                    actions:
+                      type: array
+                      description: |-
+                        The action(s) to perform when the conditions for this rule are met.
+                        See `Push Rules: API`_.
+                      items:
+                        type:
+                        - object
+                        - string
+                    event:
+                      type: object
+                      title: Event
+                      description: The Event object for the event that triggered the notification.
+                      allOf:
+                        - "$ref": "definitions/event.yaml"
+                    profile_tag:
+                      type: string
+                      description: The profile tag of the rule that matched this event.
+                    read:
+                      type: boolean
+                      description: |-
+                        Indicates whether the user has sent a read receipt indicating
+                        that they have read this message.
+                    room_id:
+                      type: string
+                      description: The ID of the room in which the event was posted.
+                    ts:
+                      type: integer
+                      description: |-
+                        The unix timestamp at which the event notification was sent,
+                        in milliseconds.
+                description: The list of events that triggered notifications.
+      tags:
+        - Push notifications

api/client-server/old_sync.yaml

@@ -0,0 +1,442 @@
+# 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>`_.
+      operationId: getEvents
+      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>`_.
+      operationId: initialSync
+      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"]
+              account_data:
+                type: array
+                description: |-
+                  The global private data created by this user.
+                items:
+                  title: Event
+                  type: object
+                  allOf:
+                    - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
+            required: ["end", "rooms", "presence"]
+        404:
+          description: There is no avatar URL for this user or this user does not exist.
+      tags:
+        - Room participation
+      deprecated: true
+  "/events/{eventId}":
+    get:
+      summary: Get a single event by event ID.
+      description: |-
+        Get a single event based on ``event_id``. You must have permission to
+        retrieve this event e.g. by being a member in the room for this event.
+
+        This endpoint was deprecated in r0 of this specification. Clients
+        should instead call the |/rooms/{roomId}/context/{eventId}|_ API.
+      operationId: getOneEvent
+      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

@@ -0,0 +1,114 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Sync Guest API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/events":
+    get:
+      summary: Listen on the event stream.
+      description: |-
+        This will listen for new events related to a particular room and return
+        them to the caller. This will block until an event is received, or until
+        the ``timeout`` is reached.
+
+        This API is the same as the normal ``/events`` endpoint, but can be
+        called by users who have not joined the room.
+
+        Note that the normal ``/events`` endpoint has been deprecated. This
+        API will also be deprecated at some point, but its replacement is not
+        yet known.
+      operationId: peekEvents
+      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

@@ -0,0 +1,225 @@
+# 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.
+      operationId: setPresence
+      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.
+      operationId: getPresence
+      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.
+      operationId: modifyPresenceList
+      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.
+      operationId: getPresenceForList
+      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

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

@@ -0,0 +1,237 @@
+# 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
+      operationId: getPushers
+      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.
+      operationId: postPusher
+      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

@@ -0,0 +1,656 @@
+# 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.
+      operationId: getPushRules
+      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.
+      operationId: getPushRule
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "nocake"
+          description: |
+            The identifier for the rule.
+      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"
+                ],
+                "pattern": "cake*lie",
+                "rule_id": "nocake",
+                "enabled": true,
+                "default": false
+              }
+          schema:
+            type: object
+            description: The push rule.
+            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.
+      operationId: deletePushRule
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "nocake"
+          description: |
+            The identifier for the rule.
+      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.
+      operationId: setPushRule
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "nocake"
+          description: |
+            The identifier for the rule.
+        - in: 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. Only applicable to ``underride`` and ``override`` rules.
+                items:
+                  type: object
+                  allOf: [ "$ref": "definitions/push_condition.yaml" ]
+              pattern:
+                type: string
+                description: |-
+                  Only applicable to ``content`` rules. The glob-style pattern to match against.
+            required: ["actions"]
+      responses:
+        200:
+          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.
+      operationId: isPushRuleEnabled
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: cake
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: nocake
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: Whether the push rule is enabled.
+          examples:
+            application/json: {
+                "enabled": true
+              }
+          schema:
+            type: object
+            properties:
+              enabled:
+                type: boolean
+                description: Whether the push rule is enabled or not.
+            required: ["enabled"]
+    put:
+      summary: "Enable or disable a push rule."
+      description: |-
+        This endpoint allows clients to enable or disable the specified push rule.
+      operationId: setPushRuleEnabled
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            ``global`` to specify global rules.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "nocake"
+          description: |
+            The identifier for the rule.
+        - in: body
+          name: body
+          description: |
+            Whether the push rule is enabled or not.
+          required: true
+          schema:
+            type: object
+            properties:
+              enabled:
+                type: boolean
+                description: Whether the push rule is enabled or not.
+            required: ["enabled"]
+            example: {
+                "enabled": true
+              }
+      responses:
+        200:
+          description: The push rule was enabled or disabled.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+      tags:
+        - Push notifications
+  "/pushrules/{scope}/{kind}/{ruleId}/actions":
+    get:
+      summary: "The actions for a push rule"
+      description:
+        This endpoint get the actions for the specified push rule.
+      operationId: getPushRuleActions
+      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: content
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: nocake
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: The actions for this push rule.
+          examples:
+            application/json: {
+                "actions": ["notify"]
+              }
+          schema:
+            type: object
+            properties:
+              actions:
+                type: array
+                description:  The action(s) to perform for this rule.
+                items:
+                  type: string
+            required: ["actions"]
+    put:
+      summary: "Set the actions for a push rule."
+      description: |-
+        This endpoint allows clients to change the actions of a push rule.
+        This can be used to change the actions of builtin rules.
+      operationId: setPushRuleActions
+      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

@@ -0,0 +1,81 @@
+# 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.
+      operationId: postReceipt
+      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

@@ -0,0 +1,92 @@
+# 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.
+      operationId: redactEvent
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room from which to redact the event.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The ID of the event to redact
+          required: true
+          x-example: "bai2b1i9:matrix.org"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "37"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "reason": "Indecent material"
+              }
+            properties:
+              reason:
+                type: string
+                description: The reason for the event being redacted.
+      responses:
+        200:
+          description: "An ID for the redaction event."
+          examples:
+            application/json: {
+                  "event_id": "YUwQidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/registration.yaml

@@ -0,0 +1,363 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Registration API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/register":
+    post:
+      summary: Register for an account on this homeserver.
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Register for an account on this homeserver.
+
+        There are two kinds of user account:
+
+        - `user` accounts. These accounts may use the full API described in this specification.
+
+        - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.
+
+        If registration is successful, this endpoint will issue an access token
+        the client can use to authorize itself in subsequent requests.
+
+        If the client does not supply a ``device_id``, the server must
+        auto-generate one.
+
+        The server SHOULD register an account with a User ID based on the
+        ``username`` provided, if any. Note that the grammar of Matrix User ID
+        localparts is restricted, so the server MUST either map the provided
+        ``username`` onto a ``user_id`` in a logical manner, or reject
+        ``username``\s which do not comply to the grammar, with
+        ``M_INVALID_USERNAME``.
+
+        Matrix clients MUST NOT assume that localpart of the registered
+        ``user_id`` matches the provided ``username``.
+
+        The returned access token must be associated with the ``device_id``
+        supplied by the client or generated by the server. The server may
+        invalidate any access token previously associated with that device. See
+        `Relationship between access tokens and devices`_.
+      operationId: register
+      parameters:
+        - in: query
+          name: kind
+          type: string
+          # swagger-UI overrides the default with the example, so better make the
+          # example the default.
+          x-example: user
+          required: false
+          default: user
+          enum:
+            - guest
+            - user
+          description: The kind of account to register. Defaults to `user`.
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API. Note that this
+                    information is *not* used to define how the registered user
+                    should be authenticated, but is instead used to
+                    authenticate the ``register`` call itself. It should be
+                    left empty, or omitted, unless an earlier call returned an
+                    response with status code 401.
+                "$ref": "definitions/auth_data.yaml"
+              bind_email:
+                type: boolean
+                description: |-
+                  If true, the server binds the email used for authentication to
+                  the Matrix ID with the ID Server.
+                example: false
+              username:
+                type: string
+                description: |-
+                  The basis for the localpart of the desired Matrix ID. If omitted,
+                  the homeserver MUST generate a Matrix ID local part.
+                example: cheeky_monkey
+              password:
+                type: string
+                description: The desired password for the account.
+                example: ilovebananas
+              device_id:
+                type: string
+                description: |-
+                  ID of the client device. If this does not correspond to a
+                  known client device, a new device will be created. The server
+                  will auto-generate a device_id if this is not specified.
+                example: GHTYAJCE
+              initial_device_display_name:
+                type: string
+                description: |-
+                  A display name to assign to the newly-created device. Ignored
+                  if ``device_id`` corresponds to a known device.
+                example: Jungle Phone
+      responses:
+        200:
+          description: The account has been registered.
+          examples:
+            application/json: {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "home_server": "matrix.org",
+                "device_id": "GHTYAJCE"
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: |-
+                  The fully-qualified Matrix user ID (MXID) that has been registered.
+
+                  Any user ID returned by this API must conform to the grammar given in the
+                  `Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.
+              access_token:
+                type: string
+                description: |-
+                  An access token for the account.
+                  This access token can then be used to authorize other requests.
+              home_server:
+                type: string
+                description: The hostname of the homeserver on which the account has been registered.
+              device_id:
+                type: string
+                description: |-
+                  ID of the registered device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+        400:
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * ``M_USER_IN_USE`` : The desired user ID is already taken.
+            * ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name.
+            * ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace
+              claimed by an application service.
+
+            These errors may be returned at any stage of the registration process,
+            including after authentication if the requested user ID was registered
+            whilst the client was performing authentication.
+
+            Homeservers MUST perform the relevant checks and return these codes before
+            performing User-Interactive Authentication, although they may also return
+            them after authentication is completed if, for example, the requested user ID
+            was registered whilst the client was performing authentication.
+          examples:
+            application/json: {
+                  "errcode": "M_USER_IN_USE",
+                  "error": "Desired user ID is already taken."
+              }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data
+  "/register/email/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given email address for the purpose of registering an account
+      description: |-
+        Proxies the identity server API ``validate/email/requestToken``, but
+        first checks that the given email address is not already associated
+        with an account on this Home Server. Note that, for consistency,
+        this API takes JSON objects, though the Identity Server API takes
+        ``x-www-form-urlencoded`` parameters. See the Identity Server API for
+        further information.
+      operationId: requestTokenToRegister
+      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: []
+      operationId: changePassword
+      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
+      operationId: requestTokenToResetPassword
+      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: []
+      operationId: deactivateAccount
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              auth:
+                description: |-
+                  Additional authentication information for the user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+      responses:
+        200:
+          description: The account has been deactivated.
+          examples:
+            application/json: {}
+          schema:
+            type: object
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+      tags:
+        - User data

api/client-server/room_initial_sync.yaml

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

api/client-server/room_send.yaml

@@ -0,0 +1,89 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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.
+      operationId: sendMessage
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to send the event to.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.message"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate an
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "msgtype": "m.text",
+                "body": "hello"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/room_state.yaml

@@ -0,0 +1,146 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server state event send API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/state/{eventType}/{stateKey}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint.  These events will be
+        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        match.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      operationId: setRoomStateWithKey
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.member"
+        - in: path
+          type: string
+          name: stateKey
+          description: The state_key for the state to send. Defaults to the empty string.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "membership": "join",
+                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
+                "displayname": "Alice Margatroid"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state/{eventType}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint. This endpoint is
+        equivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`
+        with an empty `stateKey`. Previous state events with matching
+        `<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other ``PUT`` paths because they cannot be differentiated from the
+        ``state_key``. Furthermore, ``POST`` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        `Room Events`_ for the ``m.`` event specification.
+      operationId: setRoomState
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to set the state in
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.room.name"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                  "name": "New name for the room"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: {
+                  "event_id": "YUwRidLecu"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+      tags:
+        - Room participation

api/client-server/rooms.yaml

@@ -0,0 +1,353 @@
+# 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.
+      operationId: getRoomStateWithKey
+      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.
+      operationId: getRoomStateByType
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to look up the state in.
+          required: true
+          x-example: "!636q39766251:example.com"
+        - in: path
+          type: string
+          name: eventType
+          description: The type of state to look up.
+          required: true
+          x-example: "m.room.name"
+      responses:
+        200:
+          description: The content of the state event.
+          examples:
+            application/json: {
+              "name": "Example room name"}
+          schema:
+            type: object
+        404:
+          description: The room has no state with the given type or key.
+        403:
+          description: >
+            You aren't a member of the room and weren't previously a
+            member of the room.
+      tags:
+        - Room participation
+  "/rooms/{roomId}/state":
+    get:
+      summary: Get all state events in the current state of a room.
+      description: |-
+        Get the state events for the current state of a room.
+      operationId: getRoomState
+      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.
+      operationId: getMembersByRoom
+      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 the
+            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
+  "/rooms/{roomId}/joined_members":
+    get:
+      summary: Gets the list of currently joined users and their profile data.
+      description:
+        This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room.
+        This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.
+      operationId: getJoinedMembersByRoom
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room to get the members of.
+          required: true
+          x-example: "!636q39766251:example.com"
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: |-
+            A map of MXID to room member objects.
+          examples:
+            application/json: {
+                "joined": {
+                  "@bar:example.com": {
+                    "display_name": "Bar",
+                    "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK"
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              joined:
+                additionalProperties:
+                  title: RoomMember
+                  type: object
+                  properties:
+                    display_name:
+                      type: string
+                      description: The display name of the user this object is representing.
+                    avatar_url:
+                      type: string
+                      description: The mxc avatar url of the user this object is representing.
+                description: A map from user ID to a RoomMember object.
+                type: object
+        403:
+          description: >
+            You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/search.yaml

@@ -0,0 +1,347 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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.
+      operationId: search
+      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
+                        # Within the C-S spec document, `filter`_ is picked up
+                        # as a link to the filtering section. In OpenAPI 3.0,
+                        # we could use the link feature, but we're still on 2.0
+                        # for now :/
+                        description: |-
+                          This takes a `filter`_.
+                      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

@@ -0,0 +1,368 @@
+# 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.
+      operationId: sync
+      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 wait, in milliseconds, before returning this
+            request. If no events (or other data) become available before this
+            time elapses, the server will return a response with empty fields.
+
+            By default, this is ``0``, so the server will return immediately
+            even if the response is empty.
+          x-example: 30000
+      responses:
+        200:
+          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"
+              account_data:
+                title: Account Data
+                type: object
+                description: |-
+                  The global private data created by this user.
+                allOf:
+                  - $ref: "definitions/event_batch.yaml"
+              to_device:
+                title: ToDevice
+                type: object
+                description: |-
+                  Information on the send-to-device messages for the client
+                  device, as defined in |send_to_device_sync|_.
+              device_lists:
+                title: DeviceLists
+                type: object
+                description: |-
+                  Information on end-to-end device updates, as specified in
+                  |device_lists_sync|_.
+          examples:
+            application/json: {
+                "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

@@ -0,0 +1,164 @@
+# 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.
+      operationId: getRoomTags
+      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.
+      operationId: setRoomTag
+      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.
+      operationId: deleteRoomTag
+      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

@@ -11,21 +11,34 @@
 # 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.
-openapi: 3.1.0
+swagger: '2.0'
 info:
-  title: Matrix Client-Server Room Membership API for third-party identifiers
-  version: 1.0.0
+  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.
+        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](/client-server-api/#post_matrixclientv3roomsroomidinvite).
+        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
@@ -35,18 +48,18 @@ paths:
         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`
+        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-
+        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,
+        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
+        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:
 
@@ -57,79 +70,65 @@ paths:
         - 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`_
       operationId: inviteBy3PID
       security:
-        - accessTokenQuery: []
-        - accessTokenBearer: []
+        - accessToken: []
       parameters:
         - in: path
+          type: string
           name: roomId
           description: The room identifier (not alias) to which to invite the user.
           required: true
-          example: "!d41d8cd:matrix.org"
+          x-example: "!d41d8cd:matrix.org"
+        - in: body
+          name: body
+          required: true
           schema:
-            type: string
-            format: mx-room-id
-            pattern: "^!"
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: definitions/invite_3pid.yaml
-        required: true
+            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":
+        200:
           description: The user has been invited to join the room.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "403":
+          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:
+            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.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_FORBIDDEN",
-                    "error": "@cheeky_monkey:matrix.org is banned from the room"
-                  }
-        "429":
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}
+        429:
           description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          schema:
+            "$ref": "definitions/error.yaml"
       tags:
         - Room membership
-servers:
-  - url: "{protocol}://{hostname}{basePath}"
-    variables:
-      protocol:
-        enum:
-          - http
-          - https
-        default: https
-      hostname:
-        default: localhost:8008
-      basePath:
-        default: /_matrix/client/v3
-components:
-  securitySchemes:
-    accessTokenQuery:
-      $ref: definitions/security.yaml#/accessTokenQuery
-    accessTokenBearer:
-      $ref: definitions/security.yaml#/accessTokenBearer

api/client-server/to_device.yaml

@@ -0,0 +1,90 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Send-to-device API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/sendToDevice/{eventType}/{txnId}":
+    put:
+      summary: Send an event to a given set of devices.
+      description: |-
+        This endpoint is used to send send-to-device events to a set of
+        client devices.
+      operationId: sendToDevice
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: eventType
+          description: The type of event to send.
+          required: true
+          x-example: "m.new_device"
+        - in: path
+          name: txnId
+          type: string
+          description: |-
+            The transaction ID for this event. Clients should generate an
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
+          required: true
+          x-example: "35"
+        - in: body
+          name: body
+          required: true
+          schema:
+            type: object
+            title: body
+            properties:
+              messages:
+                type: object
+                description: |-
+                  The messages to send. A map from user ID, to a map from
+                  device ID to message body. The device ID may also be `*`,
+                  meaning all known devices for the user.
+                additionalProperties:
+                  type: object
+                  additionalProperties:
+                    type: object
+                    title: EventContent
+                    description: Message content
+                example: {
+                    "@alice:example.com": {
+                      "TLLBEANAAG": {
+                        "example_content_key": "value"
+                      }
+                    }
+                  }
+      responses:
+        200:
+          description:
+            The message was successfully sent.
+          examples:
+            application/json: {
+              }
+      tags:
+        - Send-to-Device messaging

api/client-server/typing.yaml

@@ -0,0 +1,87 @@
+# 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.
+      operationId: setTyping
+      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

@@ -0,0 +1,54 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Versions API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client
+produces:
+  - application/json
+paths:
+  "/versions":
+    get:
+      summary: Gets the versions of the specification supported by the server.
+      description: |-
+        Gets the versions of the specification supported by the server.
+
+        Values will take the form ``rX.Y.Z``.
+
+        Only the latest ``Z`` value will be reported for each supported ``X.Y`` value.
+        i.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.
+      operationId: getVersions
+      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

@@ -0,0 +1,78 @@
+# 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.
+      operationId: getTurnServer
+      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/client-server/whoami.yaml

@@ -0,0 +1,53 @@
+# Copyright 2017 Travis Ralston
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Account Identification API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/account/whoami":
+    get:
+      summary: Gets information about the owner of an access token.
+      description: |-
+        Gets information about the owner of a given access token.
+      operationId: getTokenOwner
+      security:
+        - accessToken: []
+      parameters: []
+      responses:
+        200:
+          description:
+            The token belongs to a known user.
+          examples:
+            application/json: {
+                "user_id": "@joe:example.org"
+              }
+          schema:
+            type: object
+            required: ["user_id"]
+            properties:
+              user_id:
+                type: string
+                description: The user id that owns the access token.
+      tags:
+        - User data

api/files/backbone-min.js

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

@@ -0,0 +1,16 @@
+/* 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

@@ -0,0 +1,18 @@
+/*
+ * 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

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

@@ -0,0 +1,8 @@
+/*
+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

@@ -0,0 +1,125 @@
+/* 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

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

@@ -0,0 +1,32 @@
+// 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);