.buildkite/pipeline.yaml

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

.circleci/config.yml

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

.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,14 @@
-node_modules
-/data/msc
+/api/node_modules
+/assets
+/assets.tar.gz
 /env*
-/resources
-/scripts/openapi
+/scripts/gen
+/scripts/continuserv/continuserv
+/scripts/speculator/speculator
+/scripts/swagger
 /scripts/tmp
-/hugo-config.toml
-/public
+/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

CONTRIBUTING.rst

@@ -1,5 +1,5 @@
-Contributing to matrix-spec
-===========================
+Contributing to matrix-doc
+==========================
 
 Everyone is welcome to contribute to the Matrix specification!
 
@@ -9,10 +9,14 @@ 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
 ~~~~~~~~~~~~~~~~~~~~~
@@ -23,7 +27,11 @@ server before they can be documented in the specification. This process can take
 some time to complete.
 
 Changes to the protocol (new endpoints, ideas, etc) need to go through the
-`proposals process <https://matrix.org/docs/spec/proposals>`_.
+`proposals process <https://matrix.org/docs/spec/proposals>`_. Other changes,
+such as fixing bugs, typos, or clarifying existing behaviour do not need a proposal.
+If you're not sure, visit us at `#matrix-spec:matrix.org`_
+and ask.
+
 
 Other changes
 ~~~~~~~~~~~~~
@@ -36,12 +44,12 @@ 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`_.)
@@ -49,46 +57,39 @@ following:
 * 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.
 
-* 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`_. 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.
+Currently only changes to the client-server API need to end up in a changelog. The
+other APIs are not yet stable and therefore do not have a changelog. Adding to the
+changelog can only be done after you've opened your pull request, so be sure to do
+that first.
 
-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``.
+The changelog is managed by Towncrier (https://github.com/hawkowl/towncrier) in the
+form of "news fragments". The news fragments for the client-server API are stored
+under ``changelogs/client_server/newsfragments``.
 
 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\`.
+  method and route being added, surrounded in RST code tags. For example: ``POST
+  /accounts/whoami``
 
 * ``feature`` - Used when adding backwards-compatible changes to the API.
 
@@ -99,16 +100,18 @@ the ``newsfragments`` directory. The ``type`` can be one of the following:
 
 * ``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.
+the style guide and and formatting must be done using `Restructured Text
+<http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
+
+Changes that do not change the spec, such as changes to the build script, formatting,
+CSS, etc should not get a news fragment.
 
 Sign off
 --------
 
-We ask that everybody who contributes to 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 +121,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 +169,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,141 @@
+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 3.4+ virtualenv as follows::
+
+  virtualenv -p python3 env
+  env/bin/pip install -r scripts/requirements.txt
+
+(Benjamin Synders has contributed a script for `Nix`_ users, which can be
+invoked with ``nix-shell scripts/contrib/shell.nix``.)
+
+.. TODO: Possibly we need some libs installed; should record what they are.
+
+.. _`Nix`: https://nixos.org/nix/
+
+Generating the specification
+----------------------------
+
+To rebuild the specification, use ``scripts/gendoc.py``::
+
+  source env/bin/activate
+  ./scripts/gendoc.py
+
+The above will write the rendered version of the specification to
+``scripts/gen``. To view it, point your browser at ``scripts/gen/index.html``.
+
+Windows users
+~~~~~~~~~~~~~
+
+If you're on Windows Vista or higher, be sure that the "Symbolic Links"
+option was selected when installing Git prior to cloning this repository. If
+you're still seeing errors about files not being found it is likely because
+the symlink at ``api/client-server/definitions/event-schemas`` looks like a
+file. To correct the problem, open an Administrative/Elevated shell in your
+cloned matrix-doc directory and run the following::
+
+  cd api\client-server\definitions
+  del event-schemas
+  mklink /D event-schemas "..\..\..\event-schemas"
+
+This will delete the file and replace it with a symlink. Git should not detect
+this as a change, and you should be able to go back to building the project.
+
+Generating the OpenAPI (Swagger) specs
+--------------------------------------
+
+`Swagger`_ is a framework for representing RESTful APIs. We use it to generate
+interactive documentation for our APIs.
+
+Before the Swagger docs can be used in the Swagger UI (or other tool expecting
+a Swagger specs, they must be combined into a single json file. This can be
+done as follows::
+
+  source env/bin/activate
+  ./scripts/dump-swagger.py
+
+By default, ``dump-swagger`` will write to ``scripts/swagger/api-docs.json``.
+
+To make use of the generated file, there are a number of options:
+
+* It can be uploaded from your filesystem to an online editor/viewer such as
+  http://editor.swagger.io/
+* You can run a local HTTP server by running
+  ``./scripts/swagger-http-server.py``, and then view the documentation via an
+  online viewer; for example, at
+  http://petstore.swagger.io/?url=http://localhost:8000/api-docs.json
+* You can host the swagger UI yourself. See
+  https://github.com/swagger-api/swagger-ui#how-to-run for advice on how to do
+  so.
+
+.. _`Swagger`: http://swagger.io/
+
+Continuserv
+-----------
+
+Continuserv is a script which will rebuild the specification every time a file
+is changed, and will serve it to a browser over HTTP. It is intended for use by
+specification authors, so that they can quickly see the effects of their
+changes.
+
+It is written in Go, so you will need the ``go`` compiler installed on your
+computer. You will also need to install fsnotify by running::
+
+  go get gopkg.in/fsnotify/fsnotify.v1
+
+Then, create a virtualenv as described above under `Preparation`_,
+and::
+
+  source env/bin/activate
+  go run ./scripts/continuserv/main.go
+
+You will then be able to view the generated spec by visiting
+http://localhost:8000/index.html.
+
+Issue tracking
+==============
+
+Issues with the Matrix specification are tracked in `GitHub
+<https://github.com/matrix-org/matrix-doc/issues>`_.
+
+See `meta/labels.rst <meta/labels.rst>`_ for notes on what the labels mean.

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/definitions/location.yaml

@@ -17,11 +17,11 @@ properties:
     type: string
     example: "#freenode_#matrix:matrix.org"
   protocol:
-    description: The protocol ID that the third-party location is a part of.
+    description: The protocol ID that the third party location is a part of.
     type: string
     example: "irc"
   fields:
-    description: Information used to identify this third-party location.
+    description: Information used to identify this third party location.
     type: object
     example: {
       "network": "freenode",

api/application-service/definitions/location_batch.yaml

@@ -12,6 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: array
-description: List of matched third-party locations.
+description: List of matched third party locations.
 items:
   $ref: location.yaml

api/application-service/definitions/protocol.yaml

@@ -16,35 +16,36 @@ type: object
 properties:
   user_fields:
     description: |-
-      Fields which may be used to identify a third-party user. These should be
+      Fields which may be used to identify a third party user. These should be
       ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
       searched before the nickname of a user.
     type: array
     items:
       type: string
-      description: Field used to identify a third-party user.
+      description: Field used to identify a third party user.
     example: ["network", "nickname"]
   location_fields:
     description: |-
-      Fields which may be used to identify a third-party location. These should be
+      Fields which may be used to identify a third party location. These should be
       ordered to suggest the way that entities may be grouped, where higher
       groupings are ordered first. For example, the name of a network should be
       searched before the name of a channel.
     type: array
     items:
       type: string
-      description: Field used to identify a third-party location.
+      description: Field used to identify a third party location.
     example: ["network", "channel"]
   icon:
-    description: A content URI representing an icon for the third-party protocol.
+    description: A content URI representing an icon for the third party protocol.
     type: string
     example: "mxc://example.org/aBcDeFgH"
   field_types:
+    title: Field Types
     description: |-
-      The type definitions for the fields defined in `user_fields` and
-      `location_fields`. Each entry in those arrays MUST have an entry here.
-      The `string` key for this object is the field name itself.
+      The type definitions for the fields defined in the ``user_fields`` and 
+      ``location_fields``. Each entry in those arrays MUST have an entry here. The
+      ``string`` key for this object is field name itself.
 
       May be an empty object if no fields are defined.
     type: object
@@ -60,9 +61,10 @@ properties:
             may apply additional validation or filtering.
           type: string
         placeholder:
-          description: A placeholder serving as a valid example of the field value.
+          description: An placeholder serving as a valid example of the field value.
           type: string
       required: ['regexp', 'placeholder']
+    required: ['fieldname']
     example: {
       "network": {
         "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
@@ -77,4 +79,35 @@ properties:
         "placeholder": "#foobar"
       }
     }
-required: ['user_fields', 'location_fields', 'icon', 'field_types']
+  instances:
+    description: |-
+      A list of objects representing independent instances of configuration.
+      For example, multiple networks on IRC if multiple are provided by the
+      same application service.
+    type: array
+    items:
+      type: object
+      title: Protocol Instance
+      properties:
+        desc:
+          type: string
+          description: A human-readable description for the protocol, such as the name.
+          example: "Freenode"
+        icon:
+          type: string
+          description: |-
+            An optional content URI representing the protocol. Overrides the one provided
+            at the higher level Protocol object.
+          example: "mxc://example.org/JkLmNoPq"
+        fields:
+          type: object
+          description: Preset values for ``fields`` the client may use to search by.
+          example: {
+            "network": "freenode"
+          }
+        network_id:
+          type: string
+          description: A unique identifier across all instances.
+          example: "freenode"
+      required: ['desc', 'fields', 'network_id']
+required: ['user_fields', 'location_fields', 'icon', 'field_types', 'instances']

api/application-service/definitions/protocol_metadata.yaml

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

api/application-service/definitions/security.yaml

@@ -11,11 +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.
-properties:
-  events:
-    description: List of events.
-    items:
-      $ref: client_event_without_room_id.yaml
-    type: array
-type: object
-title: StateEventBatch
+homeserverAccessToken:
+  type: apiKey
+  description: The ``hs_token`` provided by the application service's registration.
+  name: access_token
+  in: query

api/application-service/definitions/user.yaml

@@ -15,15 +15,15 @@
 # TODO: Change userid to user_id as a breaking change
 properties:
   userid:
-    description: A Matrix User ID representing a third-party user.
+    description: A Matrix User ID represting a third party user.
     type: string
     example: "@_gitter_jim:matrix.org"
   protocol:
-    description: The protocol ID that the third-party location is a part of.
+    description: The protocol ID that the third party location is a part of.
     type: string
     example: "gitter"
   fields:
-    description: Information used to identify this third-party location.
+    description: Information used to identify this third party location.
     type: object
     example: {
       "user": "jim"

api/application-service/definitions/user_batch.yaml

@@ -12,6 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: array
-description: List of matched third-party users.
+description: List of matched third party users.
 items:
   $ref: user.yaml

api/application-service/protocols.yaml

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

api/application-service/query_room.yaml

@@ -12,10 +12,21 @@
 # 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 Application Service API
-  version: 1.0.0
+  title: "Matrix Application Service API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/app/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/rooms/{roomAlias}":
     get:
@@ -23,7 +34,7 @@ paths:
       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
+        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
@@ -32,76 +43,48 @@ paths:
       parameters:
         - in: path
           name: roomAlias
+          type: string
           description: The room alias being queried.
           required: true
-          example: "#magicforest:example.com"
-          schema:
-            type: string
+          x-example: "#magicforest:example.com"
       responses:
-        "200":
+        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.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "401":
+          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.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-                  }
-        "403":
-          description: The credentials supplied by the homeserver were rejected.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-                  }
-        "404":
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
           description: |-
             The application service indicates that this room alias does not exist.
             Optional error information can be included in the body of this response.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-                  }
-servers:
-  - url: "{protocol}://{hostname}{basePath}"
-    variables:
-      protocol:
-        enum:
-          - http
-          - https
-        default: https
-      hostname:
-        default: localhost:8008
-      basePath:
-        default: /_matrix/app/v1
-components:
-  securitySchemes:
-    homeserverAccessToken:
-      $ref: definitions/security.yaml#/homeserverAccessToken
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml

api/application-service/query_user.yaml

@@ -12,10 +12,21 @@
 # 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 Application Service API
-  version: 1.0.0
+  title: "Matrix Application Service API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/app/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
 paths:
   "/users/{userId}":
     get:
@@ -23,7 +34,7 @@ paths:
       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
+        inside the application service's ``users`` namespace. The homeserver will
         send this request when it receives an event for an unknown user ID in
         the application service's namespace, such as a room invite.
       operationId: queryUserById
@@ -32,73 +43,45 @@ paths:
       parameters:
         - in: path
           name: userId
+          type: string
           description: The user ID being queried.
           required: true
-          example: "@alice:example.com"
-          schema:
-            type: string
+          x-example: "@alice:example.com"
       responses:
-        "200":
+        200:
           description: |-
             The application service indicates that this user exists. The application
             service MUST create the user using the client-server API.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "401":
+          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.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
-                  }
-        "403":
-          description: The credentials supplied by the homeserver were rejected.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
-                  }
-        "404":
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_UNAUTHORIZED"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        403:
+          description: |-
+            The credentials supplied by the homeserver were rejected.
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_FORBIDDEN"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml
+        404:
           description: |-
             The application service indicates that this user does not exist.
             Optional error information can be included in the body of this response.
-          content:
-            application/json:
-              schema:
-                $ref: ../client-server/definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
-                  }
-servers:
-  - url: "{protocol}://{hostname}{basePath}"
-    variables:
-      protocol:
-        enum:
-          - http
-          - https
-        default: https
-      hostname:
-        default: localhost:8008
-      basePath:
-        default: /_matrix/app/v1
-components:
-  securitySchemes:
-    homeserverAccessToken:
-      $ref: definitions/security.yaml#/homeserverAccessToken
+          examples:
+            application/json: {
+              "errcode": "COM.EXAMPLE.MYAPPSERVICE_NOT_FOUND"
+            }
+          schema:
+            $ref: ../client-server/definitions/errors/error.yaml

api/application-service/transactions.yaml

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

api/check_examples.py

@@ -0,0 +1,157 @@
+#! /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_schema(filepath, example, schema):
+    example = resolve_references(filepath, example)
+    schema = resolve_references(filepath, schema)
+    resolver = jsonschema.RefResolver(filepath, schema, handlers={"file": load_file})
+    jsonschema.validate(example, schema, resolver=resolver)
+
+
+def check_parameter(filepath, request, parameter):
+    schema = parameter.get("schema")
+    example = schema.get('example')
+
+    if example and schema:
+        try:
+            print("Checking request schema for: %r %r" % (
+                filepath, request
+            ))
+            check_schema(filepath, example, schema)
+        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')
+    if example and schema:
+        try:
+            print ("Checking response schema for: %r %r %r" % (
+                filepath, request, code
+            ))
+            check_schema(filepath, example, schema)
+        except jsonschema.SchemaError as error:
+            for suberror in sorted(error.context, key=lambda e: e.schema_path):
+                print(list(suberror.schema_path), suberror.message, sep=", ")
+            raise ValueError("Error validating JSON schema for %r %r" % (
+                request, code
+            ), e)
+        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 resolve_references(path, schema):
+    if isinstance(schema, dict):
+        # do $ref first
+        if '$ref' in schema:
+            value = schema['$ref']
+            path = os.path.abspath(os.path.join(os.path.dirname(path), value))
+            ref = load_file("file://" + path)
+            result = resolve_references(path, ref)
+            del schema['$ref']
+        else:
+            result = {}
+
+        for key, value in schema.items():
+            result[key] = resolve_references(path, value)
+        return result
+    elif isinstance(schema, list):
+        return [resolve_references(path, value) for value in schema]
+    else:
+        return schema
+
+
+def load_file(path):
+    print("Loading reference: %s" % path)
+    if not path.startswith("file://"):
+        raise Exception("Bad ref: %s" % (path,))
+    path = path[len("file://"):]
+    with open(path, "r") as f:
+        if path.endswith(".json"):
+            return json.load(f)
+        else:
+            # We have to assume it's YAML because some of the YAML examples
+            # do not have file extensions.
+            return yaml.load(f)
+
+
+if __name__ == '__main__':
+    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,197 @@
+# 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
+    get:
+      summary: Get some account_data for the user.
+      description: |-
+        Get some account_data for the client. This config is only visible to the user
+        that set the account_data.
+      operationId: getAccountData
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          required: true
+          description: |-
+            The ID of the user to get 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 get. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.config"
+      responses:
+        200:
+          description:
+            The account data content for the given type.
+          schema:
+            type: object
+            example: {
+              "custom_account_data_key": "custom_config_value"}
+      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
+    get:
+      summary: Get some account_data for the user.
+      description: |-
+        Get some account_data for the client on a given room. This config is only
+        visible to the user that set the account_data.
+      operationId: getAccountDataPerRoom
+      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 get account_data for.
+          x-example: "!726s6s6q:example.com"
+        - in: path
+          type: string
+          name: type
+          required: true
+          description: |-
+            The event type of the account_data to get. Custom types should be
+            namespaced to avoid clashes.
+          x-example: "org.example.custom.room.config"
+      responses:
+        200:
+          description:
+            The account data content for the given type.
+          schema:
+            type: object
+            example: {
+              "custom_account_data_key": "custom_config_value"}
+      tags:
+        - User data

api/client-server/admin.yaml

@@ -0,0 +1,115 @@
+# 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: integer
+                                  format: int64
+                                  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,327 @@
+# 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",
+                  "validated_at": 1535176800000,
+                  "added_at": 1535336848756
+                }
+              ]
+            }
+          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", "msisdn"]
+                    address:
+                      type: string
+                      description: The third party identifier address.
+                    validated_at:
+                      type: integer
+                      format: int64
+                      description: |-
+                        The timestamp, in milliseconds, when the identifier was
+                        validated by the identity server.
+                    added_at:
+                      type: integer
+                      format: int64
+                      description:
+                        The timestamp, in milliseconds, when the homeserver
+                        associated the third party identifier with the user.
+                  required: ['medium', 'address', 'validated_at', 'added_at']
+      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: {
+              "submit_url": "https://example.org/path/to/submitToken"
+            }
+            schema:
+              type: object
+              properties:
+                submit_url:
+                  type: string
+                  description: |-
+                    An optional field containing a URL where the client must
+                    submit the validation token to, with identical parameters
+                    to the Identity Service API's ``POST
+                    /validate/email/submitToken`` endpoint. The homeserver must
+                    send this token to the user (if applicable), who should
+                    then be prompted to provide it to the client.
+
+                    If this field is not present, the client can assume that
+                    verification will happen without the client's involvement
+                    provided the homeserver advertises this specification version
+                    in the ``/versions`` response (ie: r0.5.0).
+                  example: "https://example.org/path/to/submitToken"
+        403:
+          description: The credentials could not be verified with the identity server.
+          examples:
+            application/json: {
+                "errcode": "M_THREEPID_AUTH_FAILED",
+                "error": "The third party credentials could not be verified by the identity server."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - User data
+  "/account/3pid/delete":
+    post:
+      summary: Deletes a third party identifier from the user's account
+      description: |-
+        Removes a third party identifier from the user's account. This might not
+        cause an unbind of the identifier from the identity server.
+      operationId: delete3pidFromAccount
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              id_server:
+                type: string
+                description: |-
+                    The identity server to unbind from. If not provided, the homeserver
+                    MUST use the ``id_server`` the identifier was added through. If the
+                    homeserver does not know the original ``id_server``, it MUST return
+                    a ``id_server_unbind_result`` of ``no-support``.
+                example: "example.org"
+              medium:
+                type: string
+                description: The medium of the third party identifier being removed.
+                enum: ["email", "msisdn"]
+                example: "email"
+              address:
+                type: string
+                description: The third party address being removed.
+                example: "example@example.org"
+            required: ['medium', 'address']
+      responses:
+        200:
+          description: |-
+            The homeserver has disassociated the third party identifier from the
+            user.
+          schema:
+            type: object
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  # XXX: I don't know why, but the order matters here so that "no-support"
+                  # doesn't become "no- support" by the renderer.
+                  - "no-support"
+                  - "success"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the 3PID from the identity server. ``success`` indicates that the
+                  indentity server has unbound the identifier whereas ``no-support``
+                  indicates that the identity server refuses to support the request
+                  or the homeserver was not able to determine an identity server to
+                  unbind from.
+                example: "success"
+            required:
+              - id_server_unbind_result
+      tags:
+        - User data
+  "/account/3pid/email/requestToken":
+    post:
+      summary: Begins the validation process for an email address for association with the user's account.
+      description: |-
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding an email address to an
+        account. This API's parameters and response are identical to that of
+        the |/register/email/requestToken|_ endpoint. The homeserver has the
+        choice of validating the email address itself, or proxying the request
+        to the ``/validate/email/requestToken`` Identity Service API as
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
+      operationId: requestTokenTo3PIDEmail
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_email_validation.yaml"
+      responses:
+        200:
+          description: |-
+            An email was sent to the given address. Note that this may be an
+            email containing the validation token or it may be informing the
+            user of an error.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "Third party identifier already in use"
+            }
+  "/account/3pid/msisdn/requestToken":
+    post:
+      summary: Begins the validation process for a phone number for association with the user's account.
+      description: |-
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. This API should
+        be used to request validation tokens when adding a phone number to an
+        account. This API's parameters and response are identical to that of
+        the |/register/msisdn/requestToken|_ endpoint. The homeserver has the
+        choice of validating the phone number itself, or proxying the request
+        to the ``/validate/msisdn/requestToken`` Identity Service API as
+        identified by ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
+      operationId: requestTokenTo3PIDMSISDN
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_msisdn_validation.yaml"
+      responses:
+        200:
+          description: An SMS message was sent to the given phone number.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The third party identifier is already in use on the homeserver, or
+            the request was invalid.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "Third party identifier already in use"
+            }

api/client-server/appservice_room_directory.yaml

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

api/client-server/banning.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 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. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked and banned from the room.
+          examples:
+            application/json: {
+              }
+          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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Room membership

api/client-server/capabilities.yaml

@@ -0,0 +1,112 @@
+# Copyright 2019 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Capabiltiies 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:
+  "/capabilities":
+    get:
+      summary: Gets information about the server's capabilities.
+      description: |-
+        Gets information about the server's supported feature set
+        and other relevant capabilities.
+      operationId: getCapabilities
+      security:
+        - accessToken: []
+      parameters: []
+      responses:
+        200:
+          description:
+            The capabilities of the server.
+          examples:
+            application/json: {
+              "capabilities": {
+                "m.change_password": {
+                  "enabled": false
+                },
+                "m.room_versions": {
+                  "default": "1",
+                  "available": {
+                    "1": "stable",
+                    "2": "stable",
+                    "3": "unstable",
+                    "test-version": "unstable"
+                  }
+                },
+                "com.example.custom.ratelimit": {
+                  "max_requests_per_hour": 600
+                }
+              }
+            }
+          schema:
+            type: object
+            required: ["capabilities"]
+            properties:
+              capabilities:
+                type: object
+                title: Capabilities
+                description: |-
+                    The custom capabilities the server supports, using the
+                    Java package naming convention.
+                additionalProperties:
+                  type: object
+                properties:
+                  "m.change_password":
+                    type: object
+                    description: |-
+                      Capability to indicate if the user can change their password.
+                    title: ChangePasswordCapability
+                    properties:
+                      enabled:
+                        type: boolean
+                        description: |-
+                          True if the user can change their password, false otherwise.
+                        example: false
+                    required: ['enabled']
+                  "m.room_versions":
+                    type: object
+                    description: The room versions the server supports.
+                    title: RoomVersionsCapability
+                    properties:
+                      default:
+                        type: string
+                        description: |-
+                          The default room version the server is using for new rooms.
+                        example: "1"
+                      available:
+                        type: object
+                        description: |-
+                          A detailed description of the room versions the server supports.
+                        additionalProperties:
+                          type: string
+                          title: RoomVersionStability
+                          enum: [stable, unstable]
+                          description: The stability of the room version.
+                    required: ['default', 'available']
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Capabilities

api/client-server/content-repo.yaml

@@ -0,0 +1,438 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2019 The Matrix.org Foundation C.I.C.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix 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: application/pdf"
+        - 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
+          x-example: "<bytes>" # so the spec shows "<bytes>" without quotes.
+          schema:
+            type: string
+            example: "<bytes>"
+            format: byte
+      responses:
+        200:
+          description: The `MXC URI`_ for the uploaded content.
+          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"
+            }
+        403:
+          description: |-
+            The user does not have permission to upload the content. Some reasons for this error include:
+
+            - The server does not permit the file type.
+            - The user has reached a quota for uploaded content.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "Cannot upload this content"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        413:
+          description: |-
+            The uploaded content is too large for the server.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Cannot upload files larger than 100mb"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/download/{serverName}/{mediaId}":
+    get:
+      summary: "Download content from the content repository."
+      operationId: getContent
+      produces: ["*/*"]
+      parameters:
+        - in: path
+          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: query
+          type: boolean
+          name: allow_remote
+          x-example: false
+          required: false
+          default: true
+          description: |
+            Indicates to the server that it should not attempt to fetch the media if it is deemed
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
+            true if not provided.
+      responses:
+        200:
+          description: "The content that was previously uploaded."
+          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
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the uploaded file."
+        502:
+          description: |-
+            The content is too large for the server to serve.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to serve"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/download/{serverName}/{mediaId}/{fileName}":
+    get:
+      summary: |-
+        Download content from the content repository. This is the same as
+        the download endpoint above, except permitting a desired file name.
+      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: A filename to give in the ``Content-Disposition`` header.
+        - in: query
+          type: boolean
+          name: allow_remote
+          x-example: false
+          required: false
+          default: true
+          description: |
+            Indicates to the server that it should not attempt to fetch the media if it is deemed
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
+            true if not provided.
+      responses:
+        200:
+          description: "The content that was previously uploaded."
+          headers:
+            Content-Type:
+              description: "The content type of the file that was previously uploaded."
+              type: "string"
+            Content-Disposition:
+              description: |-
+                The ``fileName`` requested or the name of the file that was previously
+                uploaded, if set.
+              type: "string"
+          schema:
+            type: file
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the uploaded file."
+        502:
+          description: |-
+            The content is too large for the server to serve.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to serve"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/thumbnail/{serverName}/{mediaId}":
+    get:
+      summary: |-
+        Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_
+        section for more information.
+      operationId: getContentThumbnail
+      produces: ["image/jpeg", "image/png"]
+      parameters:
+        - in: path
+          type: string
+          name: serverName
+          required: true
+          x-example: example.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
+          required: true
+          description: |-
+            The *desired* width of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+        - in: query
+          type: integer
+          x-example: 64
+          name: height
+          required: true
+          description: |-
+            The *desired* height of the thumbnail. The actual thumbnail may be
+            larger than the size specified.
+        - in: query
+          type: string
+          enum: ["crop", "scale"]
+          name: method
+          x-example: "scale"
+          description: |-
+            The desired resizing method. See the `thumbnailing <#thumbnails>`_
+            section for more information.
+        - in: query
+          type: boolean
+          name: allow_remote
+          x-example: false
+          required: false
+          default: true
+          description: |
+            Indicates to the server that it should not attempt to fetch the media if it is deemed
+            remote. This is to prevent routing loops where the server contacts itself. Defaults to
+            true if not provided.
+      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
+            # This is a workaround for us not being able to say the response is required.
+            description: "**Required.** The bytes for the thumbnail."
+        400:
+          description: |-
+            The request does not make sense to the server, or the server cannot thumbnail
+            the content. For example, the client requested non-integer dimensions or asked
+            for negatively-sized images.
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN",
+              "error": "Cannot generate thumbnails for the requested content"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        413:
+          description: |-
+            The local content is too large for the server to thumbnail.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to thumbnail"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        502:
+          description: |-
+            The remote content is too large for the server to thumbnail.
+          examples:
+            application/json: {
+              "errcode": "M_TOO_LARGE",
+              "error": "Content is too large to thumbnail"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/preview_url":
+    get:
+      summary: "Get information about a URL for a client"
+      operationId: getUrlPreview
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          x-example: "https://matrix.org"
+          name: url
+          description: "The URL to get a preview of."
+          required: true
+        - in: query
+          type: integer
+          format: int64
+          x-example: 1510610716656
+          name: ts
+          description: |-
+            The preferred point in time to return a preview for. The server may
+            return a newer version if it does not have the requested version
+            available.
+      responses:
+        200:
+          description: |-
+            The OpenGraph data for the URL, which may be empty. Some values are
+            replaced with matrix equivalents if they are provided in the response.
+            The differences from the OpenGraph protocol are described here.
+          schema:
+            type: object
+            properties:
+              "matrix:image:size":
+                type: integer
+                format: int64
+                description: |-
+                  The byte-size of the image. Omitted if there is no image attached.
+              "og:image":
+                type: string
+                description: |-
+                  An `MXC URI`_ to the image. Omitted if there is no image.
+          examples:
+            application/json: {
+                "og:title": "Matrix Blog Post",
+                "og:description": "This is a really cool blog post from matrix.org",
+                "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
+                "og:image:type": "image/png",
+                "og:image:height": 48,
+                "og:image:width": 48,
+                "matrix:image:size": 102400
+              }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Media
+  "/config":
+    get:
+      summary: Get the configuration for the content repository.
+      description: |-
+        This endpoint allows clients to retrieve the configuration of the content
+        repository, such as upload limitations.
+        Clients SHOULD use this as a guide when using content repository endpoints.
+        All values are intentionally left optional. Clients SHOULD follow
+        the advice given in the field description when the field is not available.
+
+        **NOTE:** Both clients and server administrators should be aware that proxies
+        between the client and the server may affect the apparent behaviour of content
+        repository APIs, for example, proxies may enforce a lower upload size limit
+        than is advertised by the server on this endpoint.
+      operationId: getConfig
+      produces: ["application/json"]
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The public content repository configuration for the matrix server.
+          schema:
+            type: object
+            properties:
+              m.upload.size:
+                type: integer
+                format: int64
+                description: |-
+                  The maximum size an upload can be in bytes.
+                  Clients SHOULD use this as a guide when uploading content.
+                  If not listed or null, the size limit should be treated as unknown.
+          examples:
+            application/json: {
+               "m.upload.size": 50000000
+            }
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+
+      tags:
+        - Media

api/client-server/create_room.yaml

@@ -0,0 +1,256 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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. Overridden
+           by the ``power_level_content_override`` parameter.
+
+        1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
+           ``m.room.history_visibility``, and ``m.room.guest_access`` state events.
+
+        2. Events listed in ``initial_state``, in the order that they are
+           listed.
+
+        3. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``
+           state events).
+
+        4. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with
+           ``membership: invite`` and ``m.room.third_party_invite``).
+
+        The available presets do the following with respect to room state:
+
+        ========================  ==============  ======================  ================  =========
+                 Preset           ``join_rules``  ``history_visibility``  ``guest_access``  Other
+        ========================  ==============  ======================  ================  =========
+        ``private_chat``          ``invite``      ``shared``              ``can_join``
+        ``trusted_private_chat``  ``invite``      ``shared``              ``can_join``      All invitees are given the same power level as the room creator.
+        ``public_chat``           ``public``      ``shared``              ``forbidden``
+        ========================  ==============  ======================  ================  =========
+
+        The server will create a ``m.room.create`` event in the room with the
+        requesting user as the creator, alongside other keys provided in the
+        ``creation_content``.
+      operationId: createRoom
+      security:
+        - accessToken: []
+      parameters:
+        - 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``.
+
+                  The complete room alias will become the canonical alias for
+                  the room.
+              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"]
+              room_version:
+                type: string
+                description: |-
+                  The room version to set for the room. If not provided, the homeserver is
+                  to use its configured default. If provided, the homeserver will return a
+                  400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not
+                  support the room version.
+                example: "1"
+              creation_content:
+                title: CreationContent
+                type: object
+                description: |-
+                  Extra keys, such as ``m.federate``, to be added to the content
+                  of the `m.room.create`_ event. The server will clobber the following
+                  keys: ``creator``, ``room_version``. Future versions of the specification
+                  may allow the server to clobber other keys.
+              initial_state:
+                type: array
+                description: |-
+                  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 ``preset``, but gets
+                  overriden by ``name`` and ``topic`` keys.
+                items:
+                  type: object
+                  title: StateEvent
+                  properties:
+                    type:
+                      type: string
+                      description: The type of event to send.
+                    state_key:
+                      type: string
+                      description: The state_key of the state event. Defaults to an empty string.
+                    content:
+                      type: object
+                      description: The content of the event.
+                  required: ["type", "content"]
+              preset:
+                type: string
+                enum: ["private_chat", "public_chat", "trusted_private_chat"]
+                description: |-
+                  Convenience parameter for setting various default state events
+                  based on a preset.
+
+                  If unspecified, the server should use the ``visibility`` to determine
+                  which preset to use. A visbility of ``public`` equates to a preset of
+                  ``public_chat`` and ``private`` visibility equates to a preset of
+                  ``private_chat``.
+              is_direct:
+                type: boolean
+                description: |-
+                  This flag makes the server set the ``is_direct`` flag on the
+                  ``m.room.member`` events sent to the users in ``invite`` and
+                  ``invite_3pid``. See `Direct Messaging`_ for more information.
+              power_level_content_override:
+                title: Power Level Event Content
+                type: object
+                description: |-
+                  The power level content to override in the default power level
+                  event. This object is applied on top of the generated `m.room.power_levels`_
+                  event content prior to it being sent to the room. Defaults to
+                  overriding nothing.
+      responses:
+        200:
+          description: Information about the newly created room.
+          schema:
+            type: object
+            description: Information about the newly created room.
+            properties:
+              room_id:
+                type: string
+                description: |-
+                  The created room's ID.
+            required: ['room_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``).
+
+            - The homeserver doesn't support the requested room version, or
+              one or more users being invited to the new room are residents
+              of a homeserver which does not support the requested room version.
+              The ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these
+              cases.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      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/errors/error.yaml

@@ -12,7 +12,6 @@
 # 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:
@@ -23,4 +22,4 @@ properties:
     type: string
     description: A human-readable error message.
     example: An unknown error occurred
-required: ["errcode"]
+required: ["errcode"]

api/client-server/definitions/errors/rate_limited.yaml

@@ -1,4 +1,4 @@
-# Copyright 2025 The Matrix.org Foundation C.I.C.
+# 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.
@@ -11,15 +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.
+$ref: error.yaml
 type: object
-description: |-
-  The depth field of PDUs for room version 6 and beyond.
+description: The rate limit was reached for this request
 properties:
-  # v6 enforces Canonical JSON and therefore needs a depth limit change
-  depth:
+  errcode:
+    type: string
+    description: The M_LIMIT_EXCEEDED error code
+    example: M_LIMIT_EXCEEDED
+  error:
+    type: string
+    description: A human-readable error message.
+    example: Too many requests
+  retry_after_ms:
     type: integer
     description: |-
-      The maximum depth of the `prev_events`, plus one. Must be less than the
-      maximum value for an integer (2^53 - 1). If the room's depth is already at
-      the limit, the depth must be set to the limit.
-    example: 12
+      The amount of time in milliseconds the client should wait
+      before trying the request again.
+    example: 2000
+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

@@ -16,7 +16,8 @@ properties:
   events:
     description: List of events.
     items:
-      $ref: ../../../event-schemas/schema/core-event-schema/event.yaml
+      allOf:
+      - $ref: event-schemas/schema/core-event-schema/event.yaml
+      type: object
     type: array
 type: object
-title: EventBatch

api/client-server/definitions/event_filter.yaml

@@ -14,23 +14,19 @@
 title: EventFilter
 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/public_rooms_response.yaml

@@ -0,0 +1,105 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+type: object
+description: A list of the rooms on the server.
+required: ["chunk"]
+properties:
+  chunk:
+    title: "PublicRoomsChunks"
+    type: array
+    description: |-
+      A paginated chunk of public rooms.
+    items:
+      type: object
+      title: "PublicRoomsChunk"
+      required:
+        - room_id
+        - num_joined_members
+        - world_readable
+        - guest_can_join
+      properties:
+        aliases:
+          type: array
+          description: |-
+            Aliases of the room. May be empty.
+          items:
+            type: string
+        canonical_alias:
+          type: string
+          description: |-
+            The canonical alias of the room, if any.
+        name:
+          type: string
+          description: |-
+            The name of the room, if any.
+        num_joined_members:
+          type: integer
+          description: |-
+            The number of members joined to the room.
+        room_id:
+          type: string
+          description: |-
+            The ID of the room.
+        topic:
+          type: string
+          description: |-
+            The topic of the room, if any.
+        world_readable:
+          type: boolean
+          description: |-
+            Whether the room may be viewed by guest users without joining.
+        guest_can_join:
+          type: boolean
+          description: |-
+            Whether guest users may join the room and participate in it.
+            If they can, they will be subject to ordinary power level
+            rules like any other user.
+        avatar_url:
+          type: string
+          description: The URL for the room's avatar, if one is set.
+  next_batch:
+    type: string
+    description: |-
+      A pagination token for the response. The absence of this token
+      means there are no more results to fetch and the client should
+      stop paginating.
+  prev_batch:
+    type: string
+    description: |-
+      A pagination token that allows fetching previous results. The
+      absence of this token means there are no results before this
+      batch, i.e. this is the first batch.
+  total_room_count_estimate:
+    type: integer
+    description: |-
+        An estimate on the total number of public rooms, if the
+        server has an estimate.
+example: {
+  "chunk": [
+    {
+      "aliases": ["#murrays:cheese.bar"],
+      "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
+      "guest_can_join": false,
+      "name": "CHEESE",
+      "num_joined_members": 37,
+      "room_id": "!ol19s:bleecker.street",
+      "topic": "Tasty tasty cheese",
+      "world_readable": true
+    }
+  ],
+  "next_batch": "p190q",
+  "prev_batch": "p1902",
+  "total_room_count_estimate": 115
+}

api/client-server/definitions/push_condition.yaml

@@ -18,36 +18,32 @@ properties:
   kind:
     type: string
     description: |-
-      The kind of condition to apply. See [conditions](/client-server-api/#conditions-1) for
+      The kind of condition to apply. See `conditions <#conditions>`_ for
       more information on the allowed kinds and how they work.
   key:
     type: string
     description: |-
-      Required for `event_match`, `event_property_is` and `event_property_contains`
-      conditions. The dot-separated field of the event to match.
+      Required for ``event_match`` conditions. The dot-separated field of the
+      event to match.
 
-      Required for `sender_notification_permission` conditions. The field in
+      Required for ``sender_notification_permission`` conditions. The field in
       the power level event the user needs a minimum power level for. Fields
-      must be specified under the `notifications` property in the power level
-      event's `content`.
-    example: content.body
+      must be specified under the ``notifications`` property in the power level
+      event's ``content``.
+    x-example: content.body
   pattern:
     type: string
     description: |-
-      Required for `event_match` conditions. The [glob-style pattern](/appendices#glob-style-matching)
-      to match against.
+      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
+      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 ==.
-  value:
-    type: ["string", "integer", "boolean", "null"]
-    description: |-
-      Required for `event_property_is` and `event_property_contains` conditions.
-      A non-compound [canonical JSON](/appendices#canonical-json) value to match
-      against.
 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

@@ -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,40 @@
 # 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"]
-}
 properties:
-  user_ids:
-    type: array
+  content:
     items:
-      type: string
-    description: A list of Matrix IDs of mentioned users.
+      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:
-    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.)
+    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/request_token_response.yaml

@@ -12,28 +12,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-title: RequestTokenResponse
 properties:
   sid:
     type: string
     description: |-
       The session ID. Session IDs are opaque strings that must consist entirely
-      of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255
+      of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255
       characters and they must not be empty.
     example: "123abc"
   submit_url:
     type: string
-    format: uri
     description: |-
       An optional field containing a URL where the client must submit the
       validation token to, with identical parameters to the Identity Service
-      API's `POST /validate/email/submitToken` endpoint (without the requirement
-      for an access token). The homeserver must send this token to the user (if
-      applicable), who should then be prompted to provide it to the client.
+      API's ``POST /validate/email/submitToken`` endpoint. The homeserver must
+      send this token to the user (if applicable), who should then be
+      prompted to provide it to the client.
 
       If this field is not present, the client can assume that verification
       will happen without the client's involvement provided the homeserver
-      advertises this specification version in the `/versions` response
+      advertises this specification version in the ``/versions`` response
       (ie: r0.5.0).
     example: "https://example.org/path/to/submitToken"
 required: ['sid']

api/client-server/definitions/room_event_batch.yaml

@@ -1,4 +1,4 @@
-# Copyright 2020 The Matrix.org Foundation C.I.C.
+# 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.
@@ -11,13 +11,17 @@
 # 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.
-$schema: https://json-schema.org/draft/2020-12/schema
-
-title: UnsignedData
-type: object
-description: Contains optional extra information about the event.
 properties:
-  age:
-    description: The time in milliseconds that has elapsed since the event was
-      sent.
-    type: integer
+  events:
+    description: List of events.
+    items:
+      allOf:
+      - $ref: event-schemas/schema/core-event-schema/sync_room_event.yaml
+      type: object
+      required:
+      - event_id
+      #- room_id - Not in /sync
+      - sender
+      - origin_server_ts
+    type: array
+type: object

api/client-server/definitions/room_event_filter.yaml

@@ -1,5 +1,4 @@
 # Copyright 2016 OpenMarket Ltd
-# Copyright 2022 The Matrix.org Foundation C.I.C.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -17,29 +16,23 @@ allOf:
 - type: object
   title: RoomEventFilter
   properties:
-    unread_thread_notifications:
-      type: boolean
-      description: |-
-        If `true`, enables per-[thread](/client-server-api/#threading) notification
-        counts. Only applies to the `/sync` endpoint. Defaults to `false`.
-      x-addedInMatrixVersion: "1.4"
     lazy_load_members:
       type: boolean
       description: |-
-        If `true`, enables lazy-loading of membership events. See
-        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
-        for more information. Defaults to `false`.
+        If ``true``, enables lazy-loading of membership events. See
+        `Lazy-loading room members <#lazy-loading-room-members>`_
+        for more information. Defaults to ``false``.
     include_redundant_members:
       type: boolean
       description: |-
-        If `true`, sends all membership events for all events, even if they have already
+        If ``true``, sends all membership events for all events, even if they have already
         been sent to the client. Does not
-        apply unless `lazy_load_members` is `true`. See
-        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members)
-        for more information. Defaults to `false`.
+        apply unless ``lazy_load_members`` is ``true``. See
+        `Lazy-loading room members <#lazy-loading-room-members>`_
+        for more information. Defaults to ``false``.
     not_rooms:
       description: A list of room IDs to exclude. If this list is absent then no rooms
-        are excluded. A matching room will be excluded even if it is listed in the `'rooms'`
+        are excluded. A matching room will be excluded even if it is listed in the ``'rooms'``
         filter.
       items:
         type: string
@@ -52,5 +45,5 @@ allOf:
       type: array
     contains_url:
       type: boolean
-      description: If `true`, includes only events with a `url` key in their content. If
-        `false`, excludes those events. If omitted, `url` key is not considered for filtering.
+      description: If ``true``, includes only events with a ``url`` key in their content. If
+        ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.

api/client-server/definitions/security.yaml

@@ -1,5 +1,4 @@
-# Copyright 2018 New Vector Ltd
-# Copyright 2022 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.
@@ -12,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.
-homeserverAccessToken:
-  type: http
-  scheme: bearer
-  description: The `Bearer` `hs_token` provided by the application service's registration.
+accessToken:
+  type: apiKey
+  description: The access_token returned by a call to ``/login`` or ``/register``
+  name: access_token
+  in: query

api/client-server/definitions/state_event_batch.yaml

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

api/client-server/definitions/sync_filter.yaml

@@ -16,15 +16,16 @@ 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
@@ -45,30 +46,30 @@ properties:
     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
+        title: StateFilter
         allOf:
         - $ref: room_event_filter.yaml
         description: The state events to include for rooms.

api/client-server/definitions/third_party_signed.yaml

@@ -12,10 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 type: object
-title: Third-party Signed
+title: Third Party Signed
 description: |-
-  A signature of an `m.third_party_invite` token to prove that this user
-  owns a third-party identity which has been invited to the room.
+  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
@@ -33,10 +33,6 @@ properties:
     type: object
     description: A signatures object containing a signature of the entire signed object.
     title: Signatures
-    additionalProperties:
-      type: object
-      additionalProperties:
-        type: string
     example: {
       "example.org": {
         "ed25519:0": "some9signature"

api/client-server/definitions/timeline_batch.yaml

@@ -1,4 +1,5 @@
-# Copyright 2025 The Matrix.org Foundation C.I.C.
+# 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.
@@ -11,13 +12,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: room_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 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/definitions/user_identifier.yaml

@@ -18,10 +18,7 @@ type: object
 properties:
   type:
     type: string
-    description: |-
-      The type of identification. See [Identifier types](/client-server-api/#identifier-types)
-      for supported values and additional property descriptions.
+    description: The type of identification.  See `Identifier types`_ for supported values and additional property descriptions.
 required:
   - type
-additionalProperties:
-  description: Keys dependent on the identification type.
+additionalProperties: true

api/client-server/definitions/wellknown/full.yaml

@@ -22,6 +22,7 @@ properties:
   "m.identity_server":
     $ref: "identity_server.yaml"
 additionalProperties:
+  type: object
   description: Application-dependent keys using Java package naming convention.
 required:
   - m.homeserver

api/client-server/definitions/wellknown/homeserver.yaml

@@ -18,7 +18,6 @@ type: object
 properties:
   base_url:
     type: string
-    format: uri
     description: The base URL for the homeserver for client-server connections.
     example: https://matrix.example.com
 required:

api/client-server/definitions/wellknown/identity_server.yaml

@@ -18,7 +18,6 @@ type: object
 properties:
   base_url:
     type: string
-    format: uri
     description: The base URL for the identity server for client-server connections.
     example: https://identity.example.com
 required:

api/client-server/device_management.yaml

@@ -0,0 +1,226 @@
+# 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 associated 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
+  "/delete_devices":
+    post:
+      summary: Bulk deletion of devices
+      description: |-
+        This API endpoint uses the `User-Interactive Authentication API`_.
+
+        Deletes the given devices, and invalidates any access token associated with them.
+      operationId: deleteDevices
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: body
+          schema:
+            type: object
+            properties:
+              devices:
+                type: array
+                description: The list of device IDs to delete.
+                items:
+                  type: string
+                  description: A list of device IDs.
+                example: ["QBUAZIFURK", "AUIECTSRND"]
+              auth:
+                description: |-
+                    Additional authentication information for the
+                    user-interactive authentication API.
+                "$ref": "definitions/auth_data.yaml"
+            required:
+              - devices
+      responses:
+        200:
+          description: |-
+            The devices were successfully removed, or had been removed
+            previously.
+          schema:
+            type: object
+          examples:
+            application/json: {
+              }
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+      tags:
+        - Device management

api/client-server/directory.yaml

@@ -0,0 +1,161 @@
+# 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: body
+          description: Information about this room alias.
+          required: true
+          schema:
+            type: object
+            properties:
+              room_id:
+                type: string
+                description: The room ID to set.
+            required: ['room_id']
+            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."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      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
+        404:
+          description: There is no mapped room ID for this room alias.
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Room alias #monkeys:example.org not found."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Room directory

api/client-server/event_context.yaml

@@ -0,0 +1,138 @@
+# 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.
+
+        *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_
+        for more information.
+      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": [
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                }
+              ],
+              "event": {
+                "event_id": "$f3h4d129462ha:example.com",
+                "room_id": "!636q39766251:example.com",
+                "$ref": "definitions/event-schemas/examples/m.room.message$m.image"
+              },
+              "events_before": [
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.message$m.file"
+                }
+              ],
+              "start": "t27-54_2_0_2",
+              "state": [
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.create"
+                },
+                {
+                  "room_id": "!636q39766251:example.com",
+                  "$ref": "definitions/event-schemas/examples/m.room.member"
+                }
+              ]
+            }
+      tags:
+        - Room participation

api/client-server/filter.yaml

@@ -0,0 +1,156 @@
+# 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.
+          schema:
+            type: object
+            properties:
+              filter_id:
+                type: string
+                description: |-
+                  The ID of the filter that was created. Cannot start
+                  with a ``{`` as this character is used to determine
+                  if the filter provided is inline JSON or a previously
+                  declared filter by homeservers on some APIs.
+                example: "66696p746572"
+            required: ['filter_id']
+      tags:
+        - Room participation
+  "/user/{userId}/filter/{filterId}":
+    get:
+      summary: Download a filter
+      operationId: getFilter
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          name: userId
+          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,117 @@
+# 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
+        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``).
+
+            - One or more users being invited to the room are residents of a
+              homeserver which does not support the requested room version. The
+              ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these cases.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        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"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Room membership

api/client-server/joining.yaml

@@ -0,0 +1,172 @@
+# 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
+            properties:
+              third_party_signed:
+                $ref: "definitions/third_party_signed.yaml"
+      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
+            properties:
+              room_id:
+                type: string
+                description: The joined room ID.
+            required: ["room_id"]
+        403:
+          description: |-
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+
+            - 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."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.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: query
+          type: array
+          items:
+            type: string
+          name: server_name
+          description: |-
+            The servers to attempt to join the room through. One of the servers
+            must be participating in the room.
+          x-example: ["matrix.org", "elsewhere.ca"]
+        - in: body
+          name: third_party_signed
+          schema:
+            type: object
+            properties:
+              third_party_signed:
+                $ref: "definitions/third_party_signed.yaml"
+      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
+            properties:
+              room_id:
+                type: string
+                description: The joined room ID.
+            required: ["room_id"]
+        403:
+          description: |-
+            You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:
+
+            - 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."}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Room membership

api/client-server/keys.yaml

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

api/client-server/kicking.yaml

@@ -0,0 +1,93 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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.
+        
+        Kicking a user adjusts the target member's membership state to be ``leave`` with an
+        optional ``reason``. Like with other membership changes, a user can directly adjust
+        the target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.
+      operationId: kick
+      security:
+        - accessToken: []
+      parameters:
+        - 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. This will be supplied as the 
+                  ``reason`` on the target's updated `m.room.member`_ event.
+            required: ["user_id"]
+      responses:
+        200:
+          description: The user has been kicked from the room.
+          examples:
+            application/json: {
+              }
+          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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Room membership

api/client-server/leaving.yaml

@@ -11,10 +11,21 @@
 # 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 Leaving API
-  version: 1.0.0
+  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:
@@ -33,48 +44,27 @@ paths:
         they were previously allowed to see.
       operationId: leaveRoom
       security:
-        - accessTokenQuery: []
-        - accessTokenBearer: []
+        - accessToken: []
       parameters:
         - in: path
+          type: string
           name: roomId
           description: The room identifier to leave.
           required: true
-          example: "!nkl290a:matrix.org"
-          schema:
-            type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              type: object
-              example: {
-                "reason": "Saying farewell - thanks for the support!"
-              }
-              properties:
-                reason:
-                  x-addedInMatrixVersion: "1.1"
-                  type: string
-                  description: |-
-                    Optional reason to be included as the `reason` on the subsequent
-                    membership event.
-        required: true
+          x-example: "!nkl290a:matrix.org"
       responses:
-        "200":
-          description: The room has been left.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "429":
+        200:
+          description: |-
+            The room has been left.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+        429:
           description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
       tags:
         - Room membership
   "/rooms/{roomId}/forget":
@@ -92,61 +82,35 @@ paths:
         before calling this API.
       operationId: forgetRoom
       security:
-        - accessTokenQuery: []
-        - accessTokenBearer: []
+        - accessToken: []
       parameters:
         - in: path
+          type: string
           name: roomId
           description: The room identifier to forget.
           required: true
-          example: "!au1ba7o:matrix.org"
-          schema:
-            type: string
+          x-example: "!au1ba7o:matrix.org"
       responses:
-        "200":
-          description: The room has been forgotten.
-          content:
-            application/json:
-              schema:
-                type: object
-              examples:
-                response:
-                  value: {}
-        "400":
+        200:
+          description: |-
+            The room has been forgotten.
+          examples:
+            application/json: {
+              }
+          schema:
+            type: object
+        400:
           description: The user has not left the room
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/error.yaml
-              examples:
-                response:
-                  value: {
-                    "errcode": "M_UNKNOWN",
-                    "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
-                  }
-        "429":
+          examples:
+            application/json: {
+              "errcode": "M_UNKNOWN",
+              "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
           description: This request was rate-limited.
-          content:
-            application/json:
-              schema:
-                $ref: definitions/errors/rate_limited.yaml
+          schema:
+            "$ref": "definitions/errors/rate_limited.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/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,314 @@
+# 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 Directory API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+paths:
+  "/directory/list/room/{roomId}":
+    get:
+      summary: Gets the visibility of a room in the directory
+      description: |-
+        Gets the visibility of a given room on the server's public room directory.
+      operationId: getRoomVisibilityOnDirectory
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID.
+          required: true
+          x-example: "!curbf:matrix.org"
+      responses:
+        200:
+          description: The visibility of the room in the directory
+          schema:
+            type: object
+            properties:
+              visibility:
+                type: string
+                enum: ['private', 'public']
+                description: The visibility of the room in the directory.
+          examples: 
+            application/json: {
+              "visibility": "public"
+            }
+        404:
+          description: The room is not known to the server
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Room not found"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+    put:
+      summary: Sets the visibility of a room in the room directory
+      description: |-
+        Sets the visibility of a given room in the server's public room
+        directory.
+
+        Servers may choose to implement additional access control checks
+        here, for instance that room visibility can only be changed by 
+        the room creator or a server administrator.
+      operationId: setRoomVisibilityOnDirectory
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID.
+          required: true
+          x-example: "!curbf:matrix.org"
+        - in: body
+          name: body
+          required: true
+          description: |-
+            The new visibility for the room on the room directory.
+          schema:
+            type: object
+            properties:
+              visibility:
+                type: string
+                enum: ["private", "public"]
+                description: |-
+                  The new visibility setting for the room. 
+                  Defaults to 'public'.
+            example: {
+               "visibility": "public"
+            }
+      responses:
+        200:
+          description: The visibility was updated, or no change was needed.
+          examples: 
+            application/json: {}
+        404:
+          description: The room is not known to the server
+          examples:
+            application/json: {
+              "errcode": "M_NOT_FOUND",
+              "error": "Room not found"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+  "/publicRooms":
+    get:
+      summary: Lists the public rooms on the server.
+      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: integer
+          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:
+            $ref: "definitions/public_rooms_response.yaml"
+      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: integer
+                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).
+              include_all_networks:
+                type: boolean
+                description: |-
+                  Whether or not to include all known networks/protocols from
+                  application services on the homeserver. Defaults to false.
+                example: false
+              third_party_instance_id:
+                type: string
+                description: |-
+                  The specific third party network/protocol to request from the
+                  homeserver. Can only be used if ``include_all_networks`` is false.
+                example: "irc"
+            example: {
+              "limit": 10, 
+              "filter": {
+                "generic_search_term": "foo"
+              },
+              "include_all_networks": false,
+              "third_party_instance_id": "irc"
+            }
+      responses:
+        200:
+          description: A list of the rooms on the server.
+          schema:
+            type: object
+            description: A list of the rooms on the server.
+            required: ["chunk"]
+            properties:
+              chunk:
+                title: "PublicRoomsChunks"
+                type: array
+                description: |-
+                  A paginated chunk of public rooms.
+                items:
+                  type: object
+                  title: "PublicRoomsChunk"
+                  required:
+                    - room_id
+                    - num_joined_members
+                    - world_readable
+                    - guest_can_join
+                  properties:
+                    aliases:
+                      type: array
+                      description: |-
+                        Aliases of the room. May be empty.
+                      items:
+                        type: string
+                    canonical_alias:
+                      type: string
+                      description: |-
+                        The canonical alias of the room, if any.
+                    name:
+                      type: string
+                      description: |-
+                        The name of the room, if any.
+                    num_joined_members:
+                      type: integer
+                      description: |-
+                        The number of members joined to the room.
+                    room_id:
+                      type: string
+                      description: |-
+                        The ID of the room.
+                    topic:
+                      type: string
+                      description: |-
+                        The topic of the room, if any.
+                    world_readable:
+                      type: boolean
+                      description: |-
+                        Whether the room may be viewed by guest users without joining.
+                    guest_can_join:
+                      type: boolean
+                      description: |-
+                        Whether guest users may join the room and participate in it.
+                        If they can, they will be subject to ordinary power level
+                        rules like any other user.
+                    avatar_url:
+                      type: string
+                      description: The URL for the room's avatar, if one is set.
+              next_batch:
+                type: string
+                description: |-
+                  A pagination token for the response. The absence of this token
+                  means there are no more results to fetch and the client should
+                  stop paginating.
+              prev_batch:
+                type: string
+                description: |-
+                  A pagination token that allows fetching previous results. The
+                  absence of this token means there are no results before this
+                  batch, i.e. this is the first batch.
+              total_room_count_estimate:
+                type: integer
+                description: |-
+                   An estimate on the total number of public rooms, if the
+                   server has an estimate.
+          examples:
+            application/json: {
+                "chunk": [
+                  {
+                    "aliases": ["#murrays:cheese.bar"],
+                    "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
+                    "guest_can_join": false,
+                    "name": "CHEESE",
+                    "num_joined_members": 37,
+                    "room_id": "!ol19s:bleecker.street",
+                    "topic": "Tasty tasty cheese",
+                    "world_readable": true
+                  }
+                ],
+                "next_batch": "p190q",
+                "prev_batch": "p1902",
+                "total_room_count_estimate": 115
+              }
+      tags:
+        - Room discovery

api/client-server/login.yaml

@@ -0,0 +1,208 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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":
+    get:
+      summary: Get the supported login types to authenticate users
+      description: |-
+        Gets the homeserver's supported login types to authenticate users. Clients
+        should pick one of these and supply it as the ``type`` when logging in.
+      operationId: getLoginFlows
+      responses:
+        200:
+          description: The login types the homeserver supports
+          examples:
+            application/json: {
+              "flows": [
+                {"type": "m.login.password"}
+              ]
+            }
+          schema:
+            type: object
+            properties:
+              flows:
+                type: array
+                description: The homeserver's supported login types
+                items:
+                  type: object
+                  title: LoginFlow
+                  properties:
+                    type:
+                      description: |-
+                        The login type. This is supplied as the ``type`` when
+                        logging in.
+                      type: string
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Session management
+    post:
+      summary: Authenticates the user.
+      description: |-
+        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",
+                "identifier": {
+                  "type": "m.id.user",
+                  "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.
+              identifier:
+                description: Identification information for the user.
+                "$ref": "definitions/user_identifier.yaml"
+              user:
+                type: string
+                description: The fully qualified user ID or just local part of the user ID, to log in.  Deprecated in favour of ``identifier``.
+              medium:
+                type: string
+                description: When logging in using a third party identifier, the medium of the identifier. Must be 'email'.  Deprecated in favour of ``identifier``.
+              address:
+                type: string
+                description: Third party identifier for the user.  Deprecated in favour of ``identifier``.
+              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``. Part of `Token-based`_ login.
+              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",
+                "device_id": "GHTYAJCE",
+                "well_known": {
+                  "m.homeserver": {
+                    "base_url": "https://example.org"
+                  },
+                  "m.identity_server": {
+                    "base_url": "https://id.example.org"
+                  }
+                }
+              }
+          schema:
+            type: object
+            properties:
+              user_id:
+                type: string
+                description: The fully-qualified Matrix ID that has been registered.
+              access_token:
+                type: string
+                description: |-
+                  An access token for the account.
+                  This access token can then be used to authorize other requests.
+              home_server:
+                type: string
+                description: |-
+                  The server_name of the homeserver on which the account has
+                  been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
+              device_id:
+                type: string
+                description: |-
+                  ID of the logged-in device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+              well_known:
+                type: object
+                description: |-
+                  Optional client configuration provided by the server. If present,
+                  clients SHOULD use the provided object to reconfigure themselves,
+                  optionally validating the URLs within. This object takes the same
+                  form as the one returned from .well-known autodiscovery.
+                "$ref": "definitions/wellknown/full.yaml"
+        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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        403:
+          description: |-
+            The login attempt failed. For example, the password may have been incorrect.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN"}
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Session management

api/client-server/logout.yaml

@@ -0,0 +1,72 @@
+# 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. The device associated with the access token is also deleted.
+        `Device keys <#device-keys>`_ for the device are deleted alongside the device.
+      operationId: logout
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The access token used in the request was succesfully invalidated.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - Session management
+  "/logout/all":
+    post:
+      summary: Invalidates all access tokens for a user
+      description: |-
+        Invalidates all access tokens for a user, so that they can no longer be used for
+        authorization. This includes the access token that made this request. All devices
+        for the user are also deleted. `Device keys <#device-keys>`_ for the device are
+        deleted alongside the device.
+
+        This endpoint does not require UI authorization because UI authorization is
+        designed to protect against attacks where the someone gets hold of a single access
+        token then takes over the account. This endpoint invalidates all access tokens for
+        the user, including the token used in the request, and therefore the attacker is
+        unable to take over the account in this way.
+      operationId: logout_all
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The user's access tokens were succesfully invalidated.
+          schema:
+            type: object
+            properties: {}
+      tags:
+        - Session management

api/client-server/message_pagination.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 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.
+
+        *Note*: This endpoint supports lazy-loading of room member events. See `Filtering <#lazy-loading-room-members>`_
+        for more information.
+      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. The order depends on the ``dir`` parameter.
+                  For ``dir=b`` events will be in reverse-chronological order,
+                  for ``dir=f`` in chronological order, so that events start
+                  at the ``from`` point.
+                items:
+                  type: object
+                  title: RoomEvent
+                  "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
+              state:
+                type: array
+                description: |-
+                  A list of state events relevant to showing the ``chunk``. For example, if
+                  ``lazy_load_members`` is enabled in the filter then this may contain
+                  the membership events for the senders of events in the ``chunk``.
+
+                  Unless ``include_redundant_members`` is ``true``, the server
+                  may remove membership events which would have already been
+                  sent to the client in prior calls to this endpoint, assuming
+                  the membership of those members has not changed.
+                items:
+                  type: object
+                  title: RoomStateEvent
+                  $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
+          examples:
+            application/json: {
+                "start": "t47429-4392820_219380_26003_2265",
+                "end": "t47409-4357353_219380_26003_2265",
+                "chunk": [
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                  },
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.name"
+                  },
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.video"
+                  }
+                ]
+              }
+        403:
+          description: >
+            You aren't a member of the room.
+      tags:
+        - Room participation

api/client-server/notifications.yaml

@@ -0,0 +1,133 @@
+# 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: integer
+          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": {
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                    }
+                  }
+                ]
+              }
+          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,337 @@
+# 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": [
+                  {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
+                ]
+              }
+          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": [
+                      {"$ref": "definitions/event-schemas/examples/m.presence"}
+                  ],
+                  "account_data": [
+                    {
+                      "type": "org.example.custom.config",
+                      "content": {
+                        "custom_config_key": "custom_config_value"
+                      }
+                    }
+                  ],
+                  "rooms": [
+                      {
+                          "membership": "join",
+                          "messages": {
+                              "chunk": [
+                                  {
+                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                                  },
+                                  {
+                                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                    "$ref": "definitions/event-schemas/examples/m.room.message$m.video"
+                                  }
+                              ],
+                              "end": "s3456_9_0",
+                              "start": "t44-3453_9_0"
+                          },
+                          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                          "state": [
+                              {
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                "$ref": "definitions/event-schemas/examples/m.room.join_rules"
+                              },
+                              {
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                "$ref": "definitions/event-schemas/examples/m.room.member"
+                              },
+                              {
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                "$ref": "definitions/event-schemas/examples/m.room.create"
+                              },
+                              {
+                                "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                "$ref": "definitions/event-schemas/examples/m.room.power_levels"
+                              }
+                          ],
+                          "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}/event/{eventId}|_ API
+        or 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: {"$ref": "definitions/event-schemas/examples/m.room.message$m.text"}
+          schema:
+            allOf:
+              - "$ref": "definitions/event-schemas/schema/core-event-schema/event.yaml"
+        404:
+          description: The event was not found or you do not have permission to read this event.
+      tags:
+        - Room participation
+      deprecated: true

api/client-server/openid.yaml

@@ -0,0 +1,103 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server OpenID API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/user/{userId}/openid/request_token":
+    post:
+      summary: Get an OpenID token object to verify the requester's identity.
+      description: |-
+        Gets an OpenID token object that the requester may supply to another
+        service to verify their identity in Matrix. The generated token is only
+        valid for exchanging for user information from the federation API for
+        OpenID.
+
+        The access token generated is only valid for the OpenID API. It cannot
+        be used to request another OpenID access token or call ``/sync``, for
+        example.
+      operationId: requestOpenIdToken
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: |-
+            The user to request and OpenID token for. Should be the user who
+            is authenticated for the request.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: body
+          description: An empty object. Reserved for future expansion.
+          required: true
+          schema:
+            type: object
+            example: {}
+      responses:
+        200:
+          description: |-
+            OpenID token information. This response is nearly compatible with the
+            response documented in the `OpenID 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_
+            with the only difference being the lack of an ``id_token``. Instead,
+            the Matrix homeserver's name is provided.
+          examples:
+            application/json: {
+              "access_token": "SomeT0kenHere",
+              "token_type": "Bearer",
+              "matrix_server_name": "example.com",
+              "expires_in": 3600,
+            }
+          schema:
+            type: object
+            properties:
+              access_token:
+                type: string
+                description: |-
+                  An access token the consumer may use to verify the identity of
+                  the person who generated the token. This is given to the federation
+                  API ``GET /openid/userinfo``.
+              token_type:
+                type: string
+                description: The string ``Bearer``.
+              matrix_server_name:
+                type: string
+                description: |-
+                  The homeserver domain the consumer should use when attempting to
+                  verify the user's identity.
+              expires_in:
+                type: integer
+                description: |-
+                  The number of seconds before this token expires and a new one must
+                  be generated.
+            required: ['access_token', 'token_type', 'matrix_server_name', 'expires_in']
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - OpenID

api/client-server/peeking_events.yaml

@@ -0,0 +1,106 @@
+# 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": [
+                  {
+                    "room_id": "!somewhere:over.the.rainbow",
+                    "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                  }
+                ]
+              }
+          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,138 @@
+# 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/errors/rate_limited.yaml"
+      tags:
+        - Presence
+    get:
+      summary: Get this user's presence state.
+      description: |-
+        Get the given user's presence state.
+      operationId: getPresence
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          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.
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        403:
+          description: You are not allowed to see this user's presence status.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You are not allowed to see their presence"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Presence

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/errors/rate_limited.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/errors/rate_limited.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,268 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server 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.
+                        format:
+                          type: string
+                          description: |-
+                            The format to use when sending notifications to the Push
+                            Gateway.
+                  required:
+                    - pushkey
+                    - app_id
+                    - kind
+                    - app_display_name
+                    - device_display_name
+                    - lang
+                    - data
+      tags:
+        - Push notifications
+  "/pushers/set":
+    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/_matrix/push/v1/notify",
+                "format": "event_id_only"
+              },
+              "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.
+
+                  If the ``kind`` is ``"email"``, this is the email address to
+                  send notifications to.
+              kind:
+                type: string
+                description: |-
+                  The kind of pusher to configure. ``"http"`` makes a pusher that
+                  sends HTTP pokes. ``"email"`` makes a pusher that emails the
+                  user with unread notifications. ``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.
+
+                  If the ``kind`` is ``"email"``, this is ``"m.email"``.
+              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. MUST be an HTTPS URL with a path of 
+                      ``/_matrix/push/v1/notify``.
+                    example: "https://push-gateway.location.here/_matrix/push/v1/notify"
+                  format:
+                    type: string
+                    description: |-
+                      The format to send notifications in to Push Gateways if the
+                      ``kind`` is ``http``. The details about what fields the
+                      homeserver should send to the push gateway are defined in the
+                      `Push Gateway Specification`_. Currently the only format
+                      available is 'event_id_only'.
+              append:
+                type: boolean
+                description: |-
+                  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
+            description: An empty object.
+        400:
+          description: One or more of the pusher values were invalid.
+          examples:
+            application/json: {
+              "error": "Missing parameters: lang, data",
+              "errcode": "M_MISSING_PARAM"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Push notifications

api/client-server/pushrules.yaml

@@ -0,0 +1,658 @@
+# 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.
+
+        When creating push rules, they MUST be enabled by default.
+      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 push rule was created/updated.
+          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:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.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/read_markers.yaml

@@ -0,0 +1,79 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Read Marker 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}/read_markers":
+    post:
+      summary: Set the position of the read marker for a room.
+      description: |-
+        Sets the position of the read marker for a given room, and optionally
+        the read receipt's location.
+      operationId: setReadMarker
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room ID to set the read marker in for the user.
+          required: true
+          x-example: "!somewhere:example.org"
+        - in: body
+          name: body
+          description: The read marker and optional read receipt locations.
+          required: true
+          schema:
+            type: object
+            properties:
+              "m.fully_read":
+                type: string
+                description: |-
+                  The event ID the read marker should be located at. The
+                  event MUST belong to the room.
+                example: "$somewhere:example.org"
+              "m.read":
+                type: string
+                description: |-
+                  The event ID to set the read receipt location at. This is
+                  equivalent to calling ``/receipt/m.read/$elsewhere:example.org``
+                  and is provided here to save that extra call.
+                example: "$elsewhere:example.org"
+            required: ['m.fully_read']
+      responses:
+        200:
+          description: |-
+            The read marker, and read receipt if provided, have been updated.
+          schema:
+            type: object
+            properties: {}
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - Read Markers

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/errors/rate_limited.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:example.com"
+              }
+          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,640 @@
+# 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`_, except in
+        the cases where a guest account is being registered.
+
+        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`_.
+
+        When registering a guest account, all parameters in the request body
+        with the exception of ``initial_device_display_name`` MUST BE ignored
+        by the server. The server MUST pick a ``device_id`` for the account
+        regardless of input.
+
+        Any user ID returned by this API must conform to the grammar given in the
+        `Matrix specification <../appendices.html#user-identifiers>`_.
+      operationId: register
+      parameters:
+        - in: query
+          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.
+                "$ref": "definitions/auth_data.yaml"
+              bind_email:
+                type: boolean
+                description: |-
+                  If true, the server binds the email used for authentication to
+                  the Matrix ID with the identity server.
+                example: false
+              bind_msisdn:
+                type: boolean
+                description: |-
+                  If true, the server binds the phone number used for authentication
+                  to the Matrix ID with the identity 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
+              inhibit_login:
+                type: boolean
+                description: |-
+                  If true, an ``access_token`` and ``device_id`` should not be
+                  returned from this call, therefore preventing an automatic
+                  login. Defaults to false.
+                example: false
+      responses:
+        200:
+          description: The account has been registered.
+          examples:
+            application/json: {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "access_token": "abc123",
+                "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 <../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.
+                  Required if the ``inhibit_login`` option is false.
+              home_server:
+                type: string
+                description: |-
+                  The server_name of the homeserver on which the account has
+                  been registered.
+
+                  **Deprecated**. Clients should extract the server_name from
+                  ``user_id`` (by splitting at the first colon) if they require
+                  it. Note also that ``homeserver`` is not spelt this way.
+              device_id:
+                type: string
+                description: |-
+                  ID of the registered device. Will be the same as the
+                  corresponding parameter in the request, if one was specified.
+                  Required if the ``inhibit_login`` option is false.
+            required: ['user_id']
+        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."
+              }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        403:
+          description: |-
+            The homeserver does not permit registering the account. This response
+            can be used to identify that a particular ``kind`` of account is not
+            allowed, or that registration is generally not supported by the homeserver.
+          examples:
+            application/json: {
+                "errcode": "M_FORBIDDEN",
+                "error": "Registration is disabled"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - User data
+  "/register/email/requestToken":
+    post:
+      summary: Begins the validation process for an email to be used during registration.
+      description: |-
+        The homeserver must check that the given email address is **not**
+        already associated with an account on this homeserver. The homeserver
+        has the choice of validating the email address itself, or proxying the
+        request to the ``/validate/email/requestToken`` Identity Service API. The
+        request should be proxied to the domain that is sent by the client in
+        the ``id_server``. It is imperative that the homeserver keep a list of
+        trusted Identity Servers and only proxies to those it trusts.
+      operationId: requestTokenToRegisterEmail
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_email_validation.yaml"
+      responses:
+        200:
+          description: |-
+            An email has been sent to the specified address. Note that this
+            may be an email containing the validation token or it may be
+            informing the user of an error.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: The homeserver does not permit the address to be bound.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        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 homeserver 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 homeserver in question.
+            * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
+              that is not trusted by this homeserver.
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "The specified address is already in use"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+  "/register/msisdn/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given phone number for the purpose of registering an account
+      description: |-
+        The homeserver must check that the given phone number is **not**
+        already associated with an account on this homeserver. The homeserver
+        has the choice of validating the phone number itself, or proxying the
+        request to the ``/validate/msisdn/requestToken`` Identity Service API. The
+        request should be proxied to the domain that is sent by the client in
+        the ``id_server``. It is imperative that the homeserver keep a list of
+        trusted Identity Servers and only proxies to those it trusts.
+      operationId: requestTokenToRegisterMSISDN
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_msisdn_validation.yaml"
+      responses:
+        200:
+          description: |-
+            An SMS message has been sent to the specified phone number. Note
+            that this may be an SMS message containing the validation token or
+            it may be informing the user of an error.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: The homeserver does not permit the address to be bound.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            Part of the request was invalid. This may include one of the following error codes:
+
+            * ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
+              However, if the homeserver has the ability to send SMS message, it is recommended that the server
+              instead send an SMS message to the user with instructions on how to reset their password.
+              This prevents malicious parties from being able to determine if a given phone number
+              has an account on the homeserver in question.
+            * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity server
+              that is not trusted by this homeserver.
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_IN_USE",
+              "error": "The specified address is already in use"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+  "/account/password":
+    post:
+      summary: "Changes a user's password."
+      description: |-
+        Changes the password for an account on this homeserver.
+
+        This API endpoint uses the `User-Interactive Authentication API`_ to
+        ensure the user changing the password is actually the owner of the
+        account.
+
+        An access token should be submitted to this endpoint if the client has
+        an active session.
+
+        The homeserver may change the flows available depending on whether a
+        valid access token is provided. The homeserver SHOULD NOT revoke the
+        access token provided in the request, however all other access tokens
+        for the user should be revoked if the request succeeds.
+      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/errors/rate_limited.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: |-
+        The homeserver must check that the given email address **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        ``/account/password`` endpoint.
+        
+        This API's parameters and response are identical to that of the
+        |/register/email/requestToken|_ endpoint, except that
+        ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+        given email address could be found. The server may instead send an
+        email to the given address prompting the user to create an account.
+        ``M_THREEPID_IN_USE`` may not be returned.
+        
+        The homeserver has the choice of validating the email address itself,
+        or proxying the request to the ``/validate/email/requestToken``
+        Identity Service API. The request should be proxied to the domain that
+        is sent by the client in the ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
+
+
+        .. |/register/email/requestToken| replace:: ``/register/email/requestToken``
+
+        .. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
+      operationId: requestTokenToResetPasswordEmail
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_email_validation.yaml"
+      responses:
+        200:
+          description: An email was sent to the given address.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Email not found"
+            }
+  "/account/password/msisdn/requestToken":
+    post:
+      summary: Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.
+      description: |-
+        The homeserver must check that the given phone number **is
+        associated** with an account on this homeserver. This API should be
+        used to request validation tokens when authenticating for the
+        ``/account/password`` endpoint.
+        
+        This API's parameters and response are identical to that of the
+        |/register/msisdn/requestToken|_ endpoint, except that
+        ``M_THREEPID_NOT_FOUND`` may be returned if no account matching the
+        given phone number could be found. The server may instead send the SMS
+        to the given phone number prompting the user to create an account.
+        ``M_THREEPID_IN_USE`` may not be returned.
+        
+        The homeserver has the choice of validating the phone number itself, or
+        proxying the request to the ``/validate/msisdn/requestToken`` Identity
+        Service API. The request should be proxied to the domain that is sent
+        by the client in the ``id_server``. It is imperative that the
+        homeserver keep a list of trusted Identity Servers and only proxies to
+        those that it trusts.
+
+        .. |/register/msisdn/requestToken| replace:: ``/register/msisdn/requestToken``
+
+        .. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken
+      operationId: requestTokenToResetPasswordMSISDN
+      parameters:
+        - in: body
+          name: body
+          required: true
+          schema:
+            $ref: "../identity/definitions/request_msisdn_validation.yaml"
+      responses:
+        200:
+          description: An SMS message was sent to the given phone number.
+          schema:
+            $ref: "definitions/request_token_response.yaml"
+        403:
+          description: |-
+            The homeserver does not allow the third party identifier as a
+            contact option.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_DENIED",
+              "error": "Third party identifier is not allowed"
+            }
+        400:
+          description: |-
+            The referenced third party identifier is not recognised by the
+            homeserver, or the request was invalid
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_THREEPID_NOT_FOUND",
+              "error": "Phone number not found"
+            }
+  "/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"
+              id_server:
+                type: string
+                description: |-
+                  The identity server to unbind all of the user's 3PIDs from.
+                  If not provided, the homeserver MUST use the ``id_server``
+                  that was originally use to bind each identifier. If the
+                  homeserver does not know which ``id_server`` that was,
+                  it must return an ``id_server_unbind_result`` of
+                  ``no-support``.
+                example: "example.org"
+      responses:
+        200:
+          description: The account has been deactivated.
+          schema:
+            type: object
+            properties:
+              id_server_unbind_result:
+                type: string
+                enum:
+                  - "success"
+                  - "no-support"
+                description: |-
+                  An indicator as to whether or not the homeserver was able to unbind
+                  the user's 3PIDs from the identity server(s). ``success`` indicates
+                  that all identifiers have been unbound from the identity server while
+                  ``no-support`` indicates that one or more identifiers failed to unbind
+                  due to the identity server refusing the request or the homeserver
+                  being unable to determine an identity server to unbind from. This
+                  must be ``success`` if the homeserver has no identifiers to unbind
+                  for the user.
+                example: "success"
+            required:
+              - id_server_unbind_result
+        401:
+          description: |-
+            The homeserver requires additional authentication information.
+          schema:
+            "$ref": "definitions/auth_response.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - User data
+  "/register/available":
+    get:
+      summary: Checks to see if a username is available on the server.
+      description: |-
+        Checks to see if a username is available, and valid, for the server.
+
+        The server should check to ensure that, at the time of the request, the
+        username requested is available for use. This includes verifying that an
+        application service has not claimed the username and that the username
+        fits the server's desired requirements (for example, a server could dictate
+        that it does not permit usernames with underscores).
+
+        Matrix clients may wish to use this API prior to attempting registration,
+        however the clients must also be aware that using this API does not normally
+        reserve the username. This can mean that the username becomes unavailable
+        between checking its availability and attempting to register it.
+      operationId: checkUsernameAvailability
+      parameters:
+        - in: query
+          name: username
+          type: string
+          x-example: my_cool_localpart
+          required: true
+          default: my_cool_localpart
+          description: The username to check the availability of.
+      responses:
+        200:
+          description: The username is available
+          examples:
+            application/json: {
+              "available": true
+            }
+          schema:
+            type: object
+            properties:
+              available:
+                type: boolean
+                description: |-
+                  A flag to indicate that the username is available. This should always
+                  be ``true`` when the server replies with 200 OK.
+        400:
+          description: |-
+            Part of the request was invalid or the username is not available. This may
+            include one of the following error codes:
+
+            * ``M_USER_IN_USE`` : The desired username is already taken.
+            * ``M_INVALID_USERNAME`` : The desired username is not a valid user name.
+            * ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace
+              claimed by an application service.
+          examples:
+            application/json: {
+              "errcode": "M_USER_IN_USE",
+              "error": "Desired user ID is already taken."
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/errors/rate_limited.yaml"
+      tags:
+        - User data

api/client-server/report_content.yaml

@@ -0,0 +1,78 @@
+# Copyright 2018 Travis Ralston
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Report Content API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  $ref: definitions/security.yaml
+paths:
+  "/rooms/{roomId}/report/{eventId}":
+    post:
+      summary: Reports an event as inappropriate.
+      description: |-
+        Reports an event as inappropriate to the server, which may then notify
+        the appropriate people.
+      operationId: reportContent
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which the event being reported is located.
+          required: true
+          x-example: "!637q39766251:example.com"
+        - in: path
+          type: string
+          name: eventId
+          description: The event to report.
+          required: true
+          x-example: "$something:example.org"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+              "score": -100,
+              "reason": "this makes me sad"
+            }
+            required: ['score', 'reason']
+            properties:
+              score:
+                type: integer
+                description: |-
+                  The score to rate this content as where -100 is most offensive
+                  and 0 is inoffensive.
+              reason:
+                type: string
+                description: The reason the content is being reported. May be blank.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The event has been reported successfully.
+          schema:
+            type: object
+          examples:
+            application/json: {}
+      tags:
+        - Reporting content

api/client-server/room_initial_sync.yaml

@@ -0,0 +1,156 @@
+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": [
+                    {
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.text"
+                    },
+                    {
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "definitions/event-schemas/examples/m.room.message$m.file"
+                    }
+                  ],
+                  "end": "s3456_9_0",
+                  "start": "t44-3453_9_0"
+                },
+                "room_id": "!636q39766251:example.com",
+                "state": [
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.join_rules"
+                  },
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.member"
+                  },
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.create"
+                  },
+                  {
+                    "room_id": "!636q39766251:example.com",
+                    "$ref": "definitions/event-schemas/examples/m.room.power_levels"
+                  }
+                ],
+                "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:example.com"
+              }
+          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,106 @@
+# 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: |
+        .. For backwards compatibility with older links...
+        .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:
+
+        State events can be sent using this endpoint.  These events will be
+        overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all
+        match.
+
+        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. When
+            an empty string, the trailing slash on this endpoint is optional.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: body
+          schema:
+            type: object
+            example: {
+                "membership": "join",
+                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
+                "displayname": "Alice Margatroid"
+              }
+      responses:
+        200:
+          description: "An ID for the sent event."
+          examples:
+            application/json: {
+                  "event_id": "$YUwRidLecu:example.com"
+              }
+          schema:
+            type: object
+            properties:
+              event_id:
+                type: string
+                description: |-
+                  A unique identifier for the event.
+        403:
+          description: |-
+            The sender doesn't have permission to send the event into the room.
+          schema:
+            $ref: "definitions/errors/error.yaml"
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You do not have permission to send the event."
+            }
+      tags:
+        - Room participation

api/client-server/room_upgrades.yaml

@@ -0,0 +1,93 @@
+# Copyright 2019 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server Room Upgrades 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}/upgrade":
+    post:
+      summary: Upgrades a room to a new room version.
+      description: |-
+        Upgrades the given room to a particular room version.
+      operationId: upgradeRoom
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          required: true
+          description: The ID of the room to upgrade.
+          x-example: "!oldroom:example.org"
+        - in: body
+          name: body
+          required: true
+          description: The request body
+          schema:
+            type: object
+            properties:
+              new_version:
+                type: string
+                description: The new version for the room.
+            example: {"new_version": "2"}
+            required: [new_version]
+      responses:
+        200:
+          description: The room was successfully upgraded.
+          examples:
+            application/json: {
+              "replacement_room": "!newroom:example.org"
+            }
+          schema:
+            type: object
+            properties:
+              replacement_room:
+                type: string
+                description: The ID of the new room.
+            required: [replacement_room]
+        400:
+          description: |-
+            The request was invalid. One way this can happen is if the room version
+            requested is not supported by the homeserver.
+          examples:
+            application/json: {
+              "errcode": "M_UNSUPPORTED_ROOM_VERSION",
+              "error": "This server does not support that room version"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+        403:
+          description: |-
+            The user is not permitted to upgrade the room.
+          examples:
+            application/json: {
+              "errcode": "M_FORBIDDEN",
+              "error": "You cannot upgrade this room"
+            }
+          schema:
+            "$ref": "definitions/errors/error.yaml"
+      tags:
+        - Room ugprades