Merge branch 'master' into human-id-rules

.gitignore

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

CHANGELOG.rst

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

README.rst

@@ -0,0 +1,30 @@
+This repository contains the documentation for Matrix.
+
+Structure
+=========
+
+- ``api`` : Contains the HTTP API specification.
+- ``drafts`` : Contains documents which will make it into the specification
+  and/or supporting documentation at some point in the future.
+- ``event-schemas`` : Contains the `JSON Schema`_ for all Matrix events
+  contained in the specification, along with example JSON files.
+- ``meta`` : Contains documents outlining the processes involved when writing
+  documents, e.g. documentation style, guidelines.
+- ``scripts`` : Contains scripts to generate formatted versions of the
+  documentation, typically HTML.
+- ``specification`` : Contains the specification split up into sections.
+- ``supporting-docs`` : Contains additional documents which explain design 
+  decisions, examples, use cases, etc.
+- ``templating`` : Contains the templates and templating system used to
+  generate the spec.
+
+Contributing
+============
+
+Known issues with the specification are represented as JIRA issues at
+https://matrix.org/jira/browse/SPEC
+
+If you want to ask more about the specification, or have suggestions for
+improvements, join us on ``#matrix-dev:matrix.org`` via https://matrix.org/beta.
+
+.. _JSON Schema: http://json-schema.org/

api/check_examples.py

@@ -0,0 +1,118 @@
+#! /usr/bin/env python
+
+import sys
+import json
+import os
+
+
+def import_error(module, package, debian, error):
+    sys.stderr.write((
+        "Error importing %(module)s: %(error)r\n"
+        "To install %(module)s run:\n"
+        "  pip install %(package)s\n"
+        "or on Debian run:\n"
+        "  sudo apt-get install python-%(debian)s\n"
+    ) % locals())
+    if __name__ == '__main__':
+        sys.exit(1)
+
+try:
+    import jsonschema
+except ImportError as e:
+    import_error("jsonschema", "jsonschema", "jsonschema", e)
+    raise
+
+try:
+    import yaml
+except ImportError as e:
+    import_error("yaml", "PyYAML", "yaml", e)
+    raise
+
+
+def check_parameter(filepath, request, parameter):
+    schema = parameter.get("schema")
+    example = None
+    try:
+        example_json = schema.get('example')
+        if example_json and not schema.get("format") == "byte":
+            example = json.loads(example_json)
+    except Exception as e:
+        raise ValueError("Error parsing JSON example request for %r" % (
+            request
+        ), e)
+    fileurl = "file://" + os.path.abspath(filepath)
+    if example and schema:
+        try:
+            print ("Checking request schema for: %r %r" % (
+                filepath, request
+            ))
+            # Setting the 'id' tells jsonschema where the file is so that it
+            # can correctly resolve relative $ref references in the schema
+            schema['id'] = fileurl
+            jsonschema.validate(example, schema)
+        except Exception as e:
+            raise ValueError("Error validating JSON schema for %r" % (
+                request
+            ), e)
+
+
+def check_response(filepath, request, code, response):
+    example = None
+    try:
+        example_json = response.get('examples', {}).get('application/json')
+        if example_json:
+            example = json.loads(example_json)
+    except Exception as e:
+        raise ValueError("Error parsing JSON example response for %r %r" % (
+            request, code
+        ), e)
+    schema = response.get('schema')
+    fileurl = "file://" + os.path.abspath(filepath)
+    if example and schema:
+        try:
+            print ("Checking response schema for: %r %r %r" % (
+                filepath, request, code
+            ))
+            # Setting the 'id' tells jsonschema where the file is so that it
+            # can correctly resolve relative $ref references in the schema
+            schema['id'] = fileurl
+            jsonschema.validate(example, schema)
+        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)
+
+
+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/api-docs-rooms

@@ -714,7 +714,7 @@
             },
             {
               "name": "body",
-              "description": "The typing information",
+              "description": "The typing information.",
               "required": true,
               "type": "Typing",
               "paramType": "body"

api/client-server/v1/content-repo.yaml

@@ -0,0 +1,127 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Content Repository API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /_matrix/media/v1
+produces:
+  - application/json
+  - "*/*"
+paths:
+  "/upload":
+    post:
+      summary: Upload some content to the content repository.
+      produces: ["application/json"]
+      parameters:
+        - in: header
+          name: Content-Type
+          type: string
+          description: The content type of the file being uploaded
+          x-example: "Content-Type: audio/mpeg"
+        - in: body
+          name: "<content>"
+          description: The content to be uploaded.
+          required: true
+          schema:
+            type: string
+            example: "<bytes>"
+            format: byte
+      responses:
+        200:
+          description: The MXC URI for the uploaded content.
+          schema:
+            type: object
+            required: ["content_uri"]
+            properties:
+              content_uri:
+                type: string
+                description: "The MXC URI to the uploaded content."
+          examples:
+            "application/json": |-
+              {
+                "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
+              }
+  "/download/{serverName}/{mediaId}":
+    get:
+      summary: "Download content from the content repository."
+      produces: ["*/*"]
+      parameters:
+        - in: path
+          type: string
+          name: serverName
+          x-example: matrix.org
+          required: true
+          description: |
+            The server name from the ``mxc://`` URI (the authoritory component)
+        - in: path
+          type: string
+          name: mediaId
+          x-example: ascERGshawAWawugaAcauga
+          required: true
+          description: |
+            The media ID from the ``mxc://`` URI (the path component)
+      responses:
+        200:
+          description: "The content that was previously uploaded."
+          headers:
+            Content-Type:
+              description: "The content type of the file that was previously uploaded."
+              type: "string"
+            Content-Disposition:
+              description: "The name of the file that was previously uploaded, if set."
+              type: "string"
+          schema:
+            type: file
+  "/thumbnail/{serverName}/{mediaId}":
+    get:
+      summary: "Download a thumbnail of the content from the content repository."
+      produces: ["image/jpeg", "image/png"]
+      parameters:
+        - in: path
+          type: string
+          name: serverName
+          required: true
+          x-example: matrix.org
+          description: |
+            The server name from the ``mxc://`` URI (the authoritory component)
+        - in: path
+          type: string
+          name: mediaId
+          x-example: ascERGshawAWawugaAcauga
+          required: true
+          description: |
+            The media ID from the ``mxc://`` URI (the path component)
+        - in: query
+          type: integer
+          x-example: 64
+          name: width
+          description: |-
+            The *desired* width of the thumbnail. The actual thumbnail may not
+            match the size specified.
+        - in: query
+          type: integer
+          x-example: 64
+          name: height
+          description: |-
+            The *desired* height of the thumbnail. The actual thumbnail may not
+            match the size specified.
+        - in: query
+          type: string
+          enum: ["crop", "scale"]
+          name: method
+          x-example: "scale"
+          description: The desired resizing method.
+      responses:
+        200:
+          description: "A thumbnail of the requested content."
+          headers:
+            Content-Type:
+              description: "The content type of the thumbnail."
+              type: "string"
+              enum: ["image/jpeg", "image/png"]
+          schema:
+            type: file
+            
+

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

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

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

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

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

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

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

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

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

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

api/client-server/v1/directory.yaml

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

api/client-server/v1/login.yaml

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

api/client-server/v1/membership.yaml

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

api/client-server/v1/presence.yaml

@@ -0,0 +1,208 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Presence API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/presence/{userId}/status":
+    put:
+      summary: Update this user's presence state.
+      description: |-
+        This API sets the given user's presence state. When setting the status,
+        the activity time is updated to reflect that activity; the client does
+        not need to specify the ``last_active_ago`` field. You cannot set the
+        presence state of another user.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose presence state to update.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: presenceState
+          description: The updated presence state.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "presence": "online",
+                "status_msg": "I am here."
+              }
+            properties:
+              presence:
+                type: string
+                enum: ["online", "offline", "unavailable", "free_for_chat"]
+                description: The new presence state.
+              status_msg:
+                type: string
+                description: "The status message to attach to this state."
+            required: ["presence"]
+      responses:
+        200:
+          description: The new presence state was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+    get:
+      summary: Get this user's presence state.
+      description: |-
+        Get the given user's presence state.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose presence state to get.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: The presence state for this user.
+          examples:
+            application/json: |-
+              {
+                "presence": "unavailable",
+                "last_active_ago": 420845,
+                "status_msg": null
+              }
+          schema:
+            type: object
+            properties:
+              presence:
+                type: string
+                enum: ["online", "offline", "unavailable", "free_for_chat"]
+                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.
+        404:
+          description: |-
+            There is no presence state for this user. This user may not exist or
+            isn't exposing presence information to you.
+  "/presence/list/{userId}":
+    post:
+      summary: Add or remove users from this presence list.
+      description: |-
+        Adds or removes users from this presence list.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose presence list is being modified.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: presence_diff
+          description: The modifications to make to this presence list.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "invite": [
+                  "@bob:matrix.org"
+                ],
+                "drop": [
+                  "@alice:matrix.org"
+                ]
+              }
+            properties:
+              invite:
+                type: array
+                description: A list of user IDs to add to the list.
+                items:
+                  type: string
+                  description: A list of user IDs.
+              drop:
+                type: array
+                description: A list of user IDs to remove from the list.
+                items:
+                  type: string
+                  description: A list of user IDs.
+      responses:
+        200:
+          description: The list was updated.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+    get:
+      summary: Get presence events for this presence list.
+      description: |-
+        Retrieve a list of presence events for every user on this list.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose presence list should be retrieved.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: A list of presence events for this list.
+          examples:
+            application/json: |-
+              [
+                {
+                  "content": {
+                    "avatar_url": "mxc://matrix.org/AfwefuigfWEfhuiPP",
+                    "displayname": "Alice Margatroid",
+                    "last_active_ago": 395,
+                    "presence": "offline",
+                    "user_id": "@alice:matrix.org"
+                  },
+                  "type": "m.presence"
+                },
+                {
+                  "content": {
+                    "avatar_url": "mxc://matrix.org/FWEhuiwegfWEfhuiwf",
+                    "displayname": "Marisa Kirisame",
+                    "last_active_ago": 16874,
+                    "presence": "online",
+                    "user_id": "@marisa:matrix.org"
+                  },
+                  "type": "m.presence"
+                }
+              ]
+          schema:
+            type: array
+            items:
+              type: object
+              title: PresenceEvent
+              allOf:
+                - "$ref": "core-event-schema/event.json"

api/client-server/v1/profile.yaml

@@ -0,0 +1,195 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Profile API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/profile/{userId}/displayname":
+    put:
+      summary: Set the user's display name.
+      description: |-
+        This API sets the given user's display name. You must have permission to
+        set this user's display name, e.g. you need to have their ``access_token``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose display name to set.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: displayName
+          description: The display name info.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "displayname": "Alice Margatroid"
+              }
+            properties:
+              displayname:
+                type: string
+                description: The new display name for this user.
+      responses:
+        200:
+          description: The display name was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+    get:
+      summary: Get the user's display name.
+      description: |-
+        Get the user's display name. This API may be used to fetch the user's
+        own displayname or to query the name of other users; either locally or
+        on remote homeservers.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose display name to get.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: The display name for this user.
+          examples:
+            application/json: |-
+              {
+                "displayname": "Alice Margatroid"
+              }
+          schema:
+            type: object
+            properties:
+              displayname:
+                type: string
+                description: The user's display name if they have set one.
+        404:
+          description: There is no display name for this user or this user does not exist.
+  "/profile/{userId}/avatar_url":
+    put:
+      summary: Set the user's avatar URL.
+      description: |-
+        This API sets the given user's avatar URL. You must have permission to
+        set this user's avatar URL, e.g. you need to have their ``access_token``.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose avatar URL to set.
+          required: true
+          x-example: "@alice:example.com"
+        - in: body
+          name: avatar_url
+          description: The avatar url info.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
+              }
+            properties:
+              avatar_url:
+                type: string
+                description: The new avatar URL for this user.
+      responses:
+        200:
+          description: The avatar URL was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+    get:
+      summary: Get the user's avatar URL.
+      description: |-
+        Get the user's avatar URL. This API may be used to fetch the user's
+        own avatar URL or to query the URL of other users; either locally or
+        on remote homeservers.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose avatar URL to get.
+          required: true
+          x-example: "@alice:example.com"
+      responses:
+        200:
+          description: The avatar URL for this user.
+          examples:
+            application/json: |-
+              {
+                "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
+              }
+          schema:
+            type: object
+            properties:
+              avatar_url:
+                type: string
+                description: The user's avatar URL if they have set one.
+        404:
+          description: There is no avatar URL for this user or this user does not exist.
+  "/profile/{userId}":
+    get:
+      summary: Get this user's profile information.
+      description: |-
+        Get the combined profile information for this user. This API may be used
+        to fetch the user's own profile information or other users; either
+        locally or on remote homeservers. This API may return keys which are not
+        limited to ``displayname`` or ``avatar_url``.
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user whose 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",
+                "displayname": "Alice Margatroid"
+              }
+          schema:
+            type: object
+            properties:
+              avatar_url:
+                type: string
+                description: The user's avatar URL if they have set one.
+              displayname:
+                type: string
+                description: The user's display name if they have set one.
+        404:
+          description: There is no profile information for this user or this user does not exist.

api/client-server/v1/push_notifier.yaml

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

api/client-server/v1/pusher.yaml

@@ -0,0 +1,144 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Push API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/pushers/set":
+    post:
+      summary: Modify a pusher for this user on the homeserver.
+      description: |-
+        This endpoint allows the creation, modification and deletion of `pushers`_
+        for this user ID. The behaviour of this endpoint varies depending on the
+        values in the JSON body.
+      security:
+        - accessToken: []
+      parameters:
+        - in: body
+          name: pusher
+          description: The pusher information
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "lang": "en",
+                "kind": "http",
+                "app_display_name": "Mat Rix",
+                "device_display_name": "iPhone 9",
+                "app_id": "com.example.app.ios",
+                "profile_tag": "4bea66906d0111e59d70feff819cdc9f",
+                "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ",
+                "data": {
+                  "url": "https://push-gateway.location.here"
+                },
+                "append": false
+              }
+            properties:
+              pushkey:
+                type: string
+                description: |-
+                  This is a unique identifier for this pusher. The value you
+                  should use for this is the routing or destination address
+                  information for the notification, for example, the APNS token
+                  for APNS or the Registration ID for GCM. If your notification
+                  client has no such concept, use any unique identifier.
+                  Max length, 512 bytes.
+              kind:
+                type: string
+                enum: ["http", null]
+                description: |-
+                  The kind of pusher to configure. ``"http"`` makes a pusher that
+                  sends HTTP pokes. ``null`` deletes the pusher.
+              profile_tag:
+                type: string
+                description: |-
+                  This is a string that determines what set of device rules will
+                  be matched when evaluating push rules for this pusher. It is
+                  an arbitrary string. Multiple devices may use the same
+                  ``profile_tag``. It is advised that when an app's data is
+                  copied or restored to a different device, this value remain
+                  the same. Client apps should offer ways to change the
+                  ``profile_tag``, optionally copying rules from the old
+                  profile tag. Max length, 32 bytes.
+              app_id:
+                type: string
+                description: |-
+                  This is a reverse-DNS style identifier for the application.
+                  It is recommended that this end with the platform, such that
+                  different platform versions get different app identifiers.
+                  Max length, 64 chars.
+              app_display_name:
+                type: string
+                description: |-
+                  A string that will allow the user to identify what application
+                  owns this pusher.
+              device_display_name:
+                type: string
+                description: |-
+                  A string that will allow the user to identify what device owns
+                  this pusher.
+              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.
+                properties:
+                  url:
+                    type: string
+                    description: |-
+                      Required if ``kind`` is ``http``. The URL to use to send
+                      notifications to.
+              append:
+                type: boolean
+                description: |-
+                  If true, the homeserver should add another pusher with the
+                  given pushkey and App ID in addition to any others with
+                  different user IDs. Otherwise, the Home Server must remove any
+                  other pushers with the same App ID and pushkey for different
+                  users. The default is ``false``.
+            required: ['profile_tag', 'kind', 'app_id', 'app_display_name',
+                'device_display_name', 'pushkey', 'lang', 'data']
+      responses:
+        200:
+          description: The pusher was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        400:
+          description: One or more of the pusher values were invalid.
+          examples:
+            application/json: |-
+              {
+                "error": "Missing parameters: lang, data",
+                "errcode": "M_MISSING_PARAM"
+              }
+          schema:
+            type: object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+

api/client-server/v1/pushrules.yaml

@@ -0,0 +1,488 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Push Rules API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/pushrules/":
+    get:
+      summary: Retrieve all push rulesets.
+      description: |-
+        Retrieve all push rulesets for this user. Clients can "drill-down" on
+        the rulesets by suffixing a ``scope`` to this path e.g.
+        ``/pushrules/global/``. This will return a subset of this data under the
+        specified key e.g. the ``global`` key.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: All the push rulesets for this user.
+          schema:
+            type: object
+            required: ["device", "global"]
+            properties:
+              device:
+                type: object
+                title: Devices
+                description: A dictionary of profile tags to rulesets.
+                additionalProperties:
+                    x-pattern: "$PROFILE_TAG"
+                    type: object
+                    description: The ruleset for this profile tag.
+                    title: Ruleset
+                    allOf: [
+                      "$ref": "definitions/push_ruleset.json"
+                    ]
+              global:
+                type: object
+                description: The global ruleset.
+                title: Ruleset
+                allOf: [
+                  "$ref": "definitions/push_ruleset.json"
+                ]
+          examples:
+            application/json: |-
+              {
+                "device": {},
+                "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"
+                        }
+                    ]
+                }
+              }
+  "/pushrules/{scope}/{kind}/{ruleId}":
+    get:
+      summary: Retrieve a push rule.
+      description: |-
+        Retrieve a single specified push rule.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: room
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "#spam:example.com"
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: |-
+            The specific push rule. This will also include keys specific to the
+            rule itself such as the rule's ``actions`` and ``conditions`` if set.
+          examples:
+            application/json: |-
+              {
+                "actions": [
+                    "dont_notify"
+                ],
+                "rule_id": "#spam:matrix.org",
+                "enabled": true
+              }
+          schema:
+            type: object
+            description: The push rule.
+            title: PushRule
+            allOf: [
+              "$ref": "definitions/push_rule.json"
+            ]
+    delete:
+      summary: Delete a push rule.
+      description: |-
+        This endpoint removes the push rule defined in the path.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: room
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "#spam:example.com"
+          description: |
+            The identifier for the rule.
+      responses:
+        200:
+          description: The push rule was deleted.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+    put:
+      summary: Add or change a push rule.
+      description: |-
+        This endpoint allows the creation, modification and deletion of pushers
+        for this user ID. The behaviour of this endpoint varies depending on the
+        values in the JSON body.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: room
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "#spam:example.com"
+          description: |
+            The identifier for the rule.
+        - 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 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 rule.
+        - in: body
+          name: pushrule
+          description: |-
+            The push rule data. Additional top-level keys may be present depending
+            on the parameters for the rule ``kind``.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "pattern": "cake*lie",
+                "actions": ["notify"]
+              }
+            properties:
+              actions:
+                type: array
+                description: |-
+                  The action(s) to perform when the conditions for this rule are met.
+                items:
+                  type: string
+                  enum: ["notify", "dont_notify", "coalesce", "set_tweak"]
+                  # TODO: type: object e.g. {"set_sound":"beeroclock.wav"} :/
+              conditions:
+                type: array
+                description: |-
+                  The conditions that must hold true for an event in order for a
+                  rule to be applied to an event. A rule with no conditions
+                  always matches.
+                items:
+                  type: object
+                  title: conditions
+                  allOf: [ "$ref": "definitions/push_condition.json" ]
+            required: ["actions"]
+      responses:
+        200:
+          description: The pusher was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        400:
+          description: There was a problem configuring this push rule.
+          examples:
+            application/json: |-
+              {
+                "error": "before/after rule not found: someRuleId",
+                "errcode": "M_UNKNOWN"
+              }
+          schema:
+            type: object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+  "/pushrules/{scope}/{kind}/{ruleId}/enabled":
+    put:
+      summary: "Enable or disable a push rule."
+      description: |-
+        This endpoint allows clients to enable or disable the specified push rule.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: scope
+          required: true
+          x-example: "global"
+          description: |-
+            Either ``global`` or ``device/<profile_tag>`` to specify global
+            rules or device rules for the given ``profile_tag``.
+        - in: path
+          type: string
+          name: kind
+          required: true
+          x-example: room
+          enum: ["override", "underride", "sender", "room", "content"]
+          description: |
+            The kind of rule
+        - in: path
+          type: string
+          name: ruleId
+          required: true
+          x-example: "#spam:example.com"
+          description: |
+            The identifier for the rule.
+        - in: body
+          name: <body>
+          description: |
+            Whether the push rule is enabled or not.
+          required: true
+          schema:
+            type: boolean
+            example: |-
+              true
+      responses:
+        200:
+          description: The push rule was enabled or disabled.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object

api/client-server/v1/rooms.yaml

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

api/client-server/v1/sync.yaml

@@ -0,0 +1,371 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Sync API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          type: string
+          name: from
+          description: The token to stream from.
+          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: archived
+          description: |-
+            Whether to include rooms that the user has left. If absent then
+            only rooms that the user has been invited to or has joined are
+            included. If set to "true" then rooms that the user has left are
+            included as well.
+          required: false
+          x-example: "true"
+      responses:
+        200:
+          description: "The events received, which may be none."
+          examples:
+            application/json: |-
+              {
+                "start": "s3456_9_0",
+                "end": "s3457_9_0",
+                "chunk": [
+                  {
+                    "age": 32,
+                    "content": {
+                        "body": "incoming message",
+                        "msgtype": "m.text"
+                    },
+                    "event_id": "$14328055551tzaee:localhost",
+                    "origin_server_ts": 1432804485886,
+                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                    "type": "m.room.message",
+                    "user_id": "@bob:localhost"
+                  }
+                ]
+              }
+          schema:
+            type: object
+            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: "An array of events."
+                items:
+                  type: object
+                  title: RoomEvent
+                  allOf:
+                   - "$ref": "core-event-schema/room_event.json"
+        400:
+          description: "Bad pagination ``from`` parameter."
+  "/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.
+      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"
+      responses:
+        200:
+          description: The user's current state.
+          examples:
+            application/json: |-
+              {
+                  "end": "s3456_9_0",
+                  "presence": [
+                      {
+                          "content": {
+                              "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
+                              "displayname": "Bob",
+                              "last_active_ago": 31053,
+                              "presence": "online",
+                              "user_id": "@bob:localhost"
+                          },
+                          "type": "m.presence"
+                      }
+                  ],
+                  "rooms": [
+                      {
+                          "membership": "join",
+                          "messages": {
+                              "chunk": [
+                                  {
+                                      "age": 343513403,
+                                      "content": {
+                                          "body": "foo",
+                                          "msgtype": "m.text"
+                                      },
+                                      "event_id": "$14328044851tzTJS:localhost",
+                                      "origin_server_ts": 1432804485886,
+                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                      "type": "m.room.message",
+                                      "user_id": "@alice:localhost"
+                                  },
+                                  {
+                                      "age": 343511809,
+                                      "content": {
+                                          "body": "bar",
+                                          "msgtype": "m.text"
+                                      },
+                                      "event_id": "$14328044872spjFg:localhost",
+                                      "origin_server_ts": 1432804487480,
+                                      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                      "type": "m.room.message",
+                                      "user_id": "@bob:localhost"
+                                  }
+                              ],
+                              "end": "s3456_9_0",
+                              "start": "t44-3453_9_0"
+                          },
+                          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                          "state": [
+                              {
+                                  "age": 7148266897,
+                                  "content": {
+                                      "join_rule": "public"
+                                  },
+                                  "event_id": "$14259997323TLwtb:localhost",
+                                  "origin_server_ts": 1425999732392,
+                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                  "state_key": "",
+                                  "type": "m.room.join_rules",
+                                  "user_id": "@alice:localhost"
+                              },
+                              {
+                                  "age": 6547561012,
+                                  "content": {
+                                      "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
+                                      "displayname": null,
+                                      "membership": "join"
+                                  },
+                                  "event_id": "$1426600438280zExKY:localhost",
+                                  "membership": "join",
+                                  "origin_server_ts": 1426600438277,
+                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                  "state_key": "@alice:localhost",
+                                  "type": "m.room.member",
+                                  "user_id": "@alice:localhost"
+                              },
+                              {
+                                  "age": 7148267200,
+                                  "content": {
+                                      "creator": "@alice:localhost"
+                                  },
+                                  "event_id": "$14259997320KhbwJ:localhost",
+                                  "origin_server_ts": 1425999732089,
+                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                  "state_key": "",
+                                  "type": "m.room.create",
+                                  "user_id": "@alice:localhost"
+                              },
+                              {
+                                  "age": 1622568720,
+                                  "content": {
+                                      "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
+                                      "displayname": "Bob",
+                                      "membership": "join"
+                                  },
+                                  "event_id": "$1431525430134MxlLX:localhost",
+                                  "origin_server_ts": 1431525430569,
+                                  "replaces_state": "$142652023736BSXcM:localhost",
+                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                  "state_key": "@bob:localhost",
+                                  "type": "m.room.member",
+                                  "user_id": "@bob:localhost"
+                              },
+                              {
+                                  "age": 7148267004,
+                                  "content": {
+                                      "ban": 50,
+                                      "events": {
+                                          "m.room.name": 100,
+                                          "m.room.power_levels": 100
+                                      },
+                                      "events_default": 0,
+                                      "kick": 50,
+                                      "redact": 50,
+                                      "state_default": 50,
+                                      "users": {
+                                          "@alice:localhost": 100
+                                      },
+                                      "users_default": 0
+                                  },
+                                  "event_id": "$14259997322mqfaq:localhost",
+                                  "origin_server_ts": 1425999732285,
+                                  "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
+                                  "state_key": "",
+                                  "type": "m.room.power_levels",
+                                  "user_id": "@alice:localhost"
+                              }
+                          ],
+                          "visibility": "private"
+                      }
+                  ]
+              }
+          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": "core-event-schema/event.json"
+              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": "v1-event-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": "core-event-schema/room_event.json"
+                      required: ["start", "end", "chunk"]
+                    state:
+                      type: array
+                      description: |-
+                        If the user is a member of the room this will be the
+                        current state of the room as a list of events. If the
+                        user has left the room this will be the state of the
+                        room when they left it.
+                      items:
+                        title: StateEvent
+                        type: object
+                        allOf:
+                          - "$ref": "core-event-schema/state_event.json"
+                    visibility:
+                      type: string
+                      enum: ["private", "public"]
+                      description: |-
+                        Whether this room is visible to the ``/publicRooms`` API
+                        or not."
+                  required: ["room_id", "membership"]
+            required: ["end", "rooms", "presence"]
+        404:
+          description: There is no avatar URL for this user or this user does not exist.
+  "/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.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: eventId
+          description: The event ID to get.
+          required: true
+          x-example: "$asfDuShaf7Gafaw:matrix.org"
+      responses:
+        200:
+          description: The full event.
+          examples:
+            application/json: |-
+              {
+                "content": {
+                  "body": "Hello world!",
+                  "msgtype": "m.text"
+                },
+                "room_id:": "!wfgy43Sg4a:matrix.org",
+                "user_id": "@bob:matrix.org",
+                "event_id": "$asfDuShaf7Gafaw:matrix.org",
+                "type": "m.room.message"
+              }
+          schema:
+            allOf:
+              - "$ref": "core-event-schema/event.json"
+        404:
+          description: The event was not found or you do not have permission to read this event.

api/client-server/v1/typing.yaml

@@ -0,0 +1,77 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Typing API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/typing/{userId}":
+    put:
+      summary: Informs the server that the user has started or stopped typing.
+      description: |-
+        This tells the server that the user is typing for the next N
+        milliseconds where N is the value specified in the ``timeout`` key.
+        Alternatively, if ``typing`` is ``false``, it tells the server that the
+        user has stopped typing.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: userId
+          description: The user who has started to type.
+          required: true
+          x-example: "@alice:example.com"
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which the user is typing.
+          required: true
+          x-example: "!wefh3sfukhs:example.com"
+        - in: body
+          name: typingState
+          description: The current typing state.
+          required: true
+          schema:
+            type: object
+            example: |-
+              {
+                "typing": true,
+                "timeout": 30000
+              }
+            properties:
+              typing:
+                type: boolean
+                description: |-
+                  Whether the user is typing or not. If ``false``, the ``timeout``
+                  key can be omitted.
+              timeout:
+                type: integer
+                description: The length of time in milliseconds to mark this user as typing.
+            required: ["typing"]
+      responses:
+        200:
+          description: The new typing state was set.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+

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

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

api/client-server/v1/voip.yaml

@@ -0,0 +1,68 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v1 Voice over IP API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/api/v1
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/turnServer":
+    get:
+      summary: Obtain TURN server credentials.
+      description: |-
+        This API provides credentials for the client to use when initiating
+        calls.
+      security:
+        - accessToken: []
+      responses:
+        200:
+          description: The TURN server credentials.
+          examples:
+            application/json: |-
+              {
+                "username":"1443779631:@user:example.com",
+                "password":"JlKfBy1QwLrO20385QyAtEyIv0=",
+                "uris":[
+                  "turn:turn.example.com:3478?transport=udp",
+                  "turn:10.20.30.40:3478?transport=tcp",
+                  "turns:10.20.30.40:443?transport=tcp"
+                ],
+                "ttl":86400
+              }
+          schema:
+            type: object
+            properties:
+              username:
+                type: string
+                description: |-
+                  The username to use.
+              password:
+                type: string
+                description: |-
+                  The password to use.
+              uris:
+                type: array
+                items:
+                  type: string
+                description: A list of TURN URIs
+              ttl:
+                type: integer
+                description: The time-to-live in seconds
+            required: ["username", "password", "uris", "ttl"]
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"
+

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

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

api/client-server/v2_alpha/definitions/definitions

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,22 @@
+{
+  "type": "object",
+  "allOf": [{"$ref": "definitions/event_filter.json"}],
+  "properties": {
+    "rooms": {
+      "type": "array",
+      "description":
+        "A list of room IDs to include. If this list is absent then all rooms are included. A '*' can be used as a wildcard to match any sequence of characters.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "not_rooms": {
+      "type": "array",
+      "description":
+        "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. A '*' can be used as a wildcard to match any sequence of characters.",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}

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

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

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

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

api/client-server/v2_alpha/filter.yaml

@@ -0,0 +1,139 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v2 filter API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /_matrix/client/v2_alpha
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/user/{userId}/filter":
+    post:
+      summary: Upload a new filter.
+      description: |-
+        Uploads a new filter definition to the homeserver.
+        Returns a filter ID that may be used in /sync requests to
+        retrict which events are returned to the client.
+      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.json"
+            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"]
+                  },
+                  "emphemeral": {
+                    "types": ["m.receipt", "m.typing"],
+                    "not_rooms": ["!726s6s6q:example.com"],
+                    "not_senders": ["@spam:example.com"]
+                  }
+                },
+                "presence": {
+                  "types": ["m.presence"],
+                  "not_senders": ["@alice:example.com"]
+                },
+                "event_format": "client",
+                "event_fields": ["type", "content", "sender"]
+              }
+      responses:
+        200:
+          description: The filter was created.
+          examples:
+            application/json: |-
+              {
+                "filter_id": "66696p746572"
+              }
+          schema:
+            type: object
+            properties:
+              filter_id:
+                type: string
+                description: |-
+                  The ID of the filter that was created.
+  "/user/{userId}/filter/{filterId}":
+    get:
+      summary: Download a filter
+      parameters:
+        - in: path
+          name: userId
+          type: string
+          description: |-
+            The user ID to download a filter for.
+          x-example: "@alice:example.com"
+          required: true
+        - in: path
+          name: filterId
+          type: string
+          description: |-
+            The filter ID to download.
+          x-example: "66696p746572"
+          required: true
+      responses:
+        200:
+          description: |-
+            "The filter defintion"
+          examples:
+            application/json: |-
+              {
+                "room": {
+                  "state": {
+                    "types": ["m.room.*"],
+                    "not_rooms": ["!726s6s6q:example.com"]
+                  },
+                  "timeline": {
+                    "limit": 10,
+                    "types": ["m.room.message"],
+                    "not_rooms": ["!726s6s6q:example.com"],
+                    "not_senders": ["@spam:example.com"]
+                  },
+                  "emphemeral": {
+                    "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.json"

api/client-server/v2_alpha/receipts.yaml

@@ -0,0 +1,69 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v2 Receipts API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+  - http
+basePath: /_matrix/client/v2_alpha
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/rooms/{roomId}/receipt/{receiptType}/{eventId}":
+    post:
+      summary: Send a receipt for the given event ID.
+      description: |-
+        This API updates the marker for the given receipt type to the event ID
+        specified.
+      security:
+        - accessToken: []
+      parameters:
+        - in: path
+          type: string
+          name: roomId
+          description: The room in which to send the event.
+          required: true
+          x-example: "!wefuh21ffskfuh345:example.com"
+        - in: path
+          type: string
+          name: receiptType
+          description: The type of receipt to send.
+          required: true
+          x-example: "m.read"
+          enum: ["m.read"]
+        - in: path
+          type: string
+          name: eventId
+          description: The event ID to acknowledge up to.
+          required: true
+          x-example: "$1924376522eioj:example.com"
+        - in: body
+          name: receipt
+          description: |-
+            Extra receipt information to attach to ``content`` if any. The
+            server will automatically set the ``ts`` field.
+          schema:
+            type: object
+            example: |-
+              {}
+      responses:
+        200:
+          description: The receipt was sent.
+          examples:
+            application/json: |-
+              {}
+          schema:
+            type: object  # empty json object
+        429:
+          description: This request was rate-limited.
+          schema:
+            "$ref": "definitions/error.yaml"

api/client-server/v2_alpha/sync.yaml

@@ -0,0 +1,286 @@
+swagger: '2.0'
+info:
+  title: "Matrix Client-Server v2 sync API"
+  version: "1.0.0"
+host: localhost:8008
+schemes:
+  - https
+basePath: /_matrix/client/v2_alpha
+consumes:
+  - application/json
+produces:
+  - application/json
+securityDefinitions:
+  accessToken:
+    type: apiKey
+    description: The user_id or application service access_token
+    name: access_token
+    in: query
+paths:
+  "/sync":
+    get:
+      summary: Synchronise the client's state and receive new messages.
+      description: |-
+        Synchronise the client's state with the latest state on the server.
+        Client's use this API when they first log in to get an initial snapshot
+        of the state on the server, and then continue to call this API to get
+        incremental deltas to the state, and to receive new messages.
+      security:
+        - accessToken: []
+      parameters:
+        - in: query
+          name: filter
+          type: string
+          description: |-
+            The ID of a filter created using the filter API.
+          x-example: "66696p746572"
+        - in: query
+          name: since
+          type: string
+          description: |-
+            A point in time to continue a sync from.
+          x-example: "s72594_4483_1934"
+        - in: query
+          name: set_presence
+          type: string
+          enum: ["offline"]
+          description: |-
+            Controls whether the client is automatically marked as online by
+            polling this API. If this parameter is omitted then the client is
+            automatically marked as online when it uses this API. Otherwise if
+            the parameter is set to "offline" then the client is not marked as
+            being online when it uses this API.
+          x-example: "offline"
+        - in: query
+          name: timeout
+          type: integer
+          description: |-
+            The maximum time to poll in milliseconds before returning this
+            request.
+          x-example: 30000
+      responses:
+        200:
+          description:
+            The initial snapshot or delta for the client to use to update their
+            state.
+          schema:
+            type: object
+            properties:
+              next_batch:
+                type: string
+                description: |-
+                  The batch token to supply in the ``since`` param of the next
+                  ``/sync`` request.
+              rooms:
+                title: Rooms
+                type: object
+                description: |-
+                  Updates to rooms.
+                properties:
+                  joined:
+                    title: Joined
+                    type: object
+                    additionalProperties:
+                      title: Joined Room
+                      type: object
+                      properties:
+                        event_map:
+                          title: EventMap
+                          type: object
+                          description: |-
+                            A map from event ID to events for this room. The
+                            events are referenced from the ``timeline`` and
+                            ``state`` keys for this room.
+                          additionalProperties:
+                            title: Event
+                            description: An event object.
+                            type: object
+                            allOf:
+                              - $ref: "core-event-schema/event.json"
+                        state:
+                          title: State
+                          type: object
+                          description: |-
+                            The state updates for the room.
+                          allOf:
+                            - $ref: "definitions/room_event_batch.json"
+                        timeline:
+                          title: Timeline
+                          type: object
+                          description: |-
+                            The timeline of messages and state changes in the
+                            room.
+                          allOf:
+                            - $ref: "definitions/timeline_batch.json"
+                        ephemeral:
+                          title: Ephemeral
+                          type: object
+                          description: |-
+                            The ephemeral events in the room that aren't
+                            recorded in the timeline or state of the room.
+                            e.g. typing.
+                          allOf:
+                            - $ref: "definitions/event_batch.json"
+                  invited:
+                    title: Invited
+                    type: object
+                    description: |-
+                      The rooms that the user has been invited to.
+                    additionalProperties:
+                      title: Invited Room
+                      type: object
+                      properties:
+                        invite_state:
+                          title: InviteState
+                          type: object
+                          description: |-
+                            The state of a room that the user has been invited
+                            to. These state events may only have the `sender``,
+                            ``type``, ``state_key`` and ``content`` keys
+                            present. These events do not replace any state that
+                            the client already has for the room, for example if
+                            the client has archived the room. Instead the
+                            client should keep two separate copies of the
+                            state: the one from the ``invite_state`` and one
+                            from the archived ``state``. If the client joins
+                            the room then the current state will be given as a
+                            delta against the archived ``state`` not the
+                            ``invite_state``.
+                          allOf:
+                            - $ref: "definitions/event_batch.json"
+                  archived:
+                    title: Archived
+                    type: object
+                    description: |-
+                      The rooms that the user has left or been banned from. The
+                      entries in the room_map will lack an ``ephemeral`` key.
+                    additionalProperties:
+                      title: Archived Room
+                      type: object
+                      properties:
+                        event_map:
+                          title: EventMap
+                          type: object
+                          description: |-
+                            A map from event ID to events for this room. The
+                            events are referenced from the ``timeline`` and
+                            ``state`` keys for this room.
+                          additionalProperties:
+                            title: Event
+                            description: An event object.
+                            type: object
+                            allOf:
+                              - $ref: "core-event-schema/event.json"
+                        state:
+                          title: State
+                          type: object
+                          description: |-
+                            The state updates for the room up to the point when
+                            the user left.
+                          allOf:
+                            - $ref: "definitions/room_event_batch.json"
+                        timeline:
+                          title: Timeline
+                          type: object
+                          description: |-
+                            The timeline of messages and state changes in the
+                            room up to the point when the user left.
+                          allOf:
+                            - $ref: "definitions/timeline_batch.json"
+              presence:
+                title: Presence
+                type: object
+                description: |-
+                  The updates to the presence status of other users.
+                allOf:
+                  - $ref: "definitions/event_batch.json"
+          examples:
+            application/json: |-
+              {
+                "next_batch": "s72595_4483_1934",
+                "presence": {
+                  "events": [
+                    {
+                      "sender": "@alice:example.com",
+                      "type": "m.presence",
+                      "content": {"presence": "online"}
+                    }
+                  ]
+                },
+                "rooms": {
+                  "joined": {
+                    "!726s6s6q:example.com": {
+                      "event_map": {
+                        "$66697273743031:example.com": {
+                          "sender": "@alice:example.com",
+                          "type": "m.room.member",
+                          "state_key": "@alice:example.com",
+                          "content": {"membership": "join"},
+                          "origin_server_ts": 1417731086795
+                        },
+                        "$7365636s6r6432:example.com": {
+                          "sender": "@bob:example.com",
+                          "type": "m.room.member",
+                          "state_key": "@bob:example.com",
+                          "content": {"membership": "join"},
+                          "origin_server_ts": 1417731086795
+                        },
+                        "$74686972643033:example.com": {
+                          "sender": "@alice:example.com",
+                          "type": "m.room.message",
+                          "unsigned": {"age": "124524", "txn_id": "1234"},
+                          "content": {
+                            "body": "I am a fish",
+                            "msgtype": "m.text"
+                          },
+                          "origin_server_ts": 1417731086797
+                        }
+                      },
+                      "state": {
+                        "events": [
+                          "$66697273743031:example.com",
+                          "$7365636s6r6432:example.com"
+                        ]
+                      },
+                      "timeline": {
+                        "events": [
+                          "$7365636s6r6432:example.com",
+                          "$74686972643033:example.com"
+                        ],
+                        "limited": true,
+                        "prev_batch": "t34-23535_0_0"
+                      },
+                      "ephemeral": {
+                        "events": [
+                          {
+                            "room_id": "!726s6s6q:example.com",
+                            "type": "m.typing",
+                            "content": {"user_ids": ["@alice:example.com"]}
+                          }
+                        ]
+                      }
+                    }
+                  },
+                  "invited": {
+                    "!696r7674:example.com": {
+                      "invite_state": {
+                        "events": [
+                          {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.name",
+                            "state_key": "",
+                            "content": {"name": "My Room Name"}
+                          },
+                          {
+                            "sender": "@alice:example.com",
+                            "type": "m.room.member",
+                            "state_key": "@bob:example.com",
+                            "content": {"membership": "invite"}
+                          }
+                        ]
+                      }
+                    }
+                  },
+                  "archived": {}
+                }
+              }

api/package.json

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

api/swagger.html

@@ -61,11 +61,9 @@
 </head>
 
 <body class="swagger-section">
-<div id="header">
+<div id="swagger-header">
   <div class="swagger-ui-wrap">
-    <a id="logo" href="http://swagger.wordnik.com/">swagger</a>
     <form id="api_selector">
-      <div class="input"><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"></div>
       <div class="input"><input placeholder="access_token" id="input_apiKey" name="apiKey" type="text"></div>
     </form>
   </div>

api/validator.js

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

attic/v1_registration_login.rst

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

drafts/address-book-repo.rst

@@ -0,0 +1,14 @@
+Address book repository
+=======================
+
+.. NOTE::
+  This section is a work in progress.
+
+.. TODO-spec
+  Do we even need it?  Clients can use out-of-band addressbook servers for now;
+  this should definitely not be core.
+  - format: POST(?) wodges of json, some possible processing, then return wodges of json on GET.
+  - processing may remove dupes, merge contacts, pepper with extra info (e.g. matrix-ability of
+    contacts), etc.
+  - Standard json format for contacts? Piggy back off vcards?
+

drafts/application_services.rst

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

drafts/as-http-api.rst

@@ -0,0 +1,574 @@
+.. TODO
+  Sometimes application services need to create rooms (e.g. when lazy loading 
+  from room aliases). Created rooms need to have a user that created them, so 
+  federation works (as it relies on an entry existing in m.room.member). We 
+  should be able to add metadata to m.room.member to state that this user is an 
+  application service, a virtual user, etc.
+
+
+Application Services HTTP API
+=============================
+
+.. contents:: Table of Contents
+
+.. sectnum::
+
+Application Service -> Home Server
+----------------------------------
+This contains home server APIs which are used by the application service.
+
+Registration API ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This API registers the application service with its host homeserver to offer its
+services.
+
+Inputs:
+ - Credentials (e.g. some kind of string token)
+ - Namespace[users]
+ - Namespace[room aliases]
+ - URL base to receive inbound comms
+Output:
+ - The credentials the HS will use to query the AS with in return. (e.g. some 
+   kind of string token)
+Side effects:
+ - The HS will start delivering events to the URL base specified if this 200s.
+API called when:
+ - The application service wants to register with a brand new home server.
+Notes:
+ - An application service can state whether they should be the only ones who 
+   can manage a specified namespace. This is referred to as an "exclusive" 
+   namespace. An exclusive namespace prevents humans and other application 
+   services from creating/deleting entities in that namespace. Typically,
+   exclusive namespaces are used when the rooms represent real rooms on
+   another service (e.g. IRC). Non-exclusive namespaces are used when the
+   application service is merely augmenting the room itself (e.g. providing
+   logging or searching facilities).
+ - Namespaces are represented by POSIX extended regular expressions in JSON. 
+   They look like::
+
+     users: [
+       {
+         "exclusive": true,
+         "regex": "@irc\.freenode\.net/.*"
+       }
+     ]
+
+::
+
+ POST /register
+ 
+ Request format
+ {
+   url: "https://my.application.service.com/matrix/",
+   as_token: "some_AS_token",
+   namespaces: {
+     users: [
+       {
+         "exclusive": true,
+         "regex": "@irc\.freenode\.net/.*"
+       }
+     ],
+     aliases: [
+       {
+         "exclusive": true,
+         "regex": "#irc\.freenode\.net/.*"
+       }
+     ],
+     rooms: [
+       {
+         "exclusive": true,
+         "regex": "!irc\.freenode\.net/.*"
+       }
+     ]
+   }
+ }
+ 
+ 
+ Returns:
+   200 : Registration accepted.
+   400 : Namespaces do not conform to regex
+   401 : Credentials need to be supplied.
+   403 : AS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {
+     hs_token: "string"
+   }
+   
+Unregister API ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+This API unregisters a previously registered AS from the home server.
+
+Inputs:
+ - AS token
+Output:
+ - None.
+Side effects:
+ - The HS will stop delivering events to the URL base specified for this AS if 
+   this 200s.
+API called when:
+ - The application service wants to stop receiving all events from the HS.
+ 
+::
+
+  POST /unregister
+
+  Request format
+  {
+    as_token: "string"
+  }
+
+
+Home Server -> Application Service
+----------------------------------
+This contains application service APIs which are used by the home server.
+
+User Query ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~
+
+This API is called by the HS to query the existence of a user on the Application
+Service's namespace.
+
+Inputs:
+ - User ID
+ - HS Credentials
+Output:
+ - Whether the user exists.
+Side effects:
+ - User is created on the HS by the AS via CS APIs during the processing of this request.
+API called when:
+ - HS receives an event for an unknown user ID in the AS's namespace, e.g. an
+   invite event to a room.
+Notes:
+ - When the AS receives this request, if the user exists, it must create the user via
+   the CS API.
+ - It can also set arbitrary information about the user (e.g. display name, join rooms, etc)
+   using the CS API.
+ - When this setup is complete, the AS should respond to the HS request. This means the AS 
+   blocks the HS until the user is created.
+ - This is deemed more flexible than alternative methods (e.g. returning a JSON blob with the
+   user's display name and get the HS to provision the user).
+Retry notes:
+ - The home server cannot respond to the client's request until the response to
+   this API is obtained from the AS.
+ - Recommended that home servers try a few times then time out, returning a
+   408 Request Timeout to the client.
+   
+::
+
+ GET /users/$user_id?access_token=$hs_token
+ 
+ Returns:
+   200 : User is recognised.
+   404 : User not found.
+   401 : Credentials need to be supplied.
+   403 : HS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {}
+   
+Room Alias Query ``[Draft]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This API is called by the HS to query the existence of a room alias on the 
+Application Service's namespace.
+
+Inputs:
+ - Room alias
+ - HS Credentials
+Output:
+ - Whether the room exists.
+Side effects:
+ - Room is created on the HS by the AS via CS APIs during the processing of 
+   this request.
+API called when:
+ - HS receives an event to join a room alias in the AS's namespace.
+Notes:
+ - When the AS receives this request, if the room exists, it must create the room via
+   the CS API.
+ - It can also set arbitrary information about the room (e.g. name, topic, etc)
+   using the CS API.
+ - It can send messages as other users in order to populate scrollback.
+ - When this setup is complete, the AS should respond to the HS request. This means the AS 
+   blocks the HS until the room is created and configured.
+ - This is deemed more flexible than alternative methods (e.g. returning an initial sync
+   style JSON blob and get the HS to provision the room). It also means that the AS knows
+   the room ID -> alias mapping.
+Retry notes:
+ - The home server cannot respond to the client's request until the response to
+   this API is obtained from the AS.
+ - Recommended that home servers try a few times then time out, returning a
+   408 Request Timeout to the client.
+ 
+::
+
+ GET /rooms/$room_alias?access_token=$hs_token
+ 
+ Returns:
+   200 : Room is recognised.
+   404 : Room not found.
+   401 : Credentials need to be supplied.
+   403 : HS credentials rejected.
+ 
+ 
+   200 OK response format
+ 
+   {}
+
+Pushing ``[Draft]``
+~~~~~~~~~~~~~~~~~~~
+This API is called by the HS when the HS wants to push an event (or batch of 
+events) to the AS.
+
+Inputs:
+ - HS Credentials
+ - Event(s) to give to the AS
+ - HS-generated transaction ID
+Output:
+ - None. 
+
+Data flows:
+
+::
+
+ Typical
+ HS ---> AS : Home server sends events with transaction ID T.
+    <---    : AS sends back 200 OK.
+    
+ AS ACK Lost
+ HS ---> AS : Home server sends events with transaction ID T.
+    <-/-    : AS 200 OK is lost.
+ HS ---> AS : Home server retries with the same transaction ID of T.
+    <---    : AS sends back 200 OK. If the AS had processed these events 
+              already, it can NO-OP this request (and it knows if it is the same
+              events based on the transacton ID).
+            
+
+Retry notes:
+ - If the HS fails to pass on the events to the AS, it must retry the request.
+ - Since ASes by definition cannot alter the traffic being passed to it (unlike
+   say, a Policy Server), these requests can be done in parallel to general HS
+   processing; the HS doesn't need to block whilst doing this.
+ - Home servers should use exponential backoff as their retry algorithm.
+ - Home servers MUST NOT alter (e.g. add more) events they were going to 
+   send within that transaction ID on retries, as the AS may have already 
+   processed the events.
+    
+Ordering notes:
+ - The events sent to the AS should be linearised, as they are from the event
+   stream.
+ - The home server will need to maintain a queue of transactions to send to 
+   the AS.
+
+::
+
+  PUT /transactions/$transaction_id?access_token=$hs_token
+ 
+  Request format
+  {
+    events: [
+      ...
+    ]
+  }
+
+Client-Server v2 API Extensions
+-------------------------------
+
+Identity assertion
+~~~~~~~~~~~~~~~~~~
+The client-server API infers the user ID from the ``access_token`` provided in 
+every request. It would be an annoying amount of book-keeping to maintain tokens
+for every virtual user. It would be preferable if the application service could
+use the CS API with its own ``as_token`` instead, and specify the virtual user
+they wish to be acting on behalf of. For real users, this would require 
+additional permissions granting the AS permission to masquerade as a matrix user.
+
+Inputs:
+ - Application service token (``access_token``)
+
+ Either:
+   - User ID in the AS namespace to act as.
+ Or:
+   - OAuth2 token of real user (which may end up being an access token) 
+Notes:
+ - This will apply on all aspects of the CS API, except for Account Management.
+ - The ``as_token`` is inserted into ``access_token`` which is usually where the
+   client token is. This is done on purpose to allow application services to 
+   reuse client SDKs.
+
+::
+
+ /path?access_token=$token&user_id=$userid
+
+ Query Parameters:
+   access_token: The application service token
+   user_id: The desired user ID to act as.
+   
+ /path?access_token=$token&user_token=$token
+
+ Query Parameters:
+   access_token: The application service token
+   user_token: The token granted to the AS by the real user
+
+Timestamp massaging
+~~~~~~~~~~~~~~~~~~~
+The application service may want to inject events at a certain time (reflecting
+the time on the network they are tracking e.g. irc, xmpp). Application services
+need to be able to adjust the ``origin_server_ts`` value to do this.
+
+Inputs:
+ - Application service token (``as_token``)
+ - Desired timestamp
+Notes:
+ - This will only apply when sending events.
+ 
+::
+
+ /path?access_token=$token&ts=$timestamp
+
+ Query Parameters added to the send event APIs only:
+   access_token: The application service token
+   ts: The desired timestamp
+
+Server admin style permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The home server needs to give the application service *full control* over its
+namespace, both for users and for room aliases. This means that the AS should
+be able to create/edit/delete any room alias in its namespace, as well as
+create/delete any user in its namespace. No additional API changes need to be
+made in order for control of room aliases to be granted to the AS. Creation of
+users needs API changes in order to:
+
+- Work around captchas.
+- Have a 'passwordless' user.
+
+This involves bypassing the registration flows entirely. This is achieved by
+including the AS token on a ``/register`` request, along with a login type of
+``m.login.application_service`` to set the desired user ID without a password.
+
+::
+
+  /register?access_token=$as_token
+  
+  Content:
+  {
+    type: "m.login.application_service",
+    user: "<desired user localpart in AS namespace>"
+  }
+  
+Application services which attempt to create users or aliases *outside* of
+their defined namespaces will receive an error code ``M_EXCLUSIVE``. Similarly,
+normal users who attempt to create users or alises *inside* an application
+service-defined namespace will receive the same ``M_EXCLUSIVE`` error code.
+
+ID conventions ``[Draft]``
+--------------------------
+.. NOTE::
+  - Giving HSes the freedom to namespace still feels like the Right Thing here.
+  - Exposing a public API provides the consistency which was the main complaint
+    against namespacing.
+  - This may have knock-on effects for the AS registration API. E.g. why don't
+    we let ASes specify the *URI* regex they want?
+
+This concerns the well-defined conventions for mapping 3P network IDs to matrix
+IDs, which we expect clients to be able to do by themselves.
+
+User IDs
+~~~~~~~~
+Matrix users may wish to directly contact a virtual user, e.g. to send an email.
+The URI format is a well-structured way to represent a number of different ID
+types, including:
+
+- MSISDNs (``tel``)
+- Email addresses (``mailto``)
+- IRC nicks (``irc`` - https://tools.ietf.org/html/draft-butcher-irc-url-04)
+- XMPP (xep-0032)
+- SIP URIs (RFC 3261)
+
+As a result, virtual user IDs SHOULD relate to their URI counterpart. This
+mapping from URI to user ID can be expressed in a number of ways:
+
+- Expose a C-S API on the HS which takes URIs and responds with user IDs.
+- Munge the URI with the user ID.
+
+Exposing an API would allow HSes to internally map user IDs however they like,
+at the cost of an extra round trip (of which the response can be cached).
+Munging the URI would allow clients to apply the mapping locally, but would force
+user X on service Y to always map to the same munged user ID. Considering the
+exposed API could just be applying this munging, there is more flexibility if
+an API is exposed. 
+
+::
+
+  GET /_matrix/app/v1/user?uri=$url_encoded_uri
+  
+  Returns 200 OK:
+  {
+    user_id: <complete user ID on local HS>
+  }
+
+Room Aliases
+~~~~~~~~~~~~
+We may want to expose some 3P network rooms so Matrix users can join them directly,
+e.g. IRC rooms. We don't want to expose every 3P network room though, e.g. mailto,
+tel. Rooms which are publicly accessible (e.g. IRC rooms) can be exposed as an alias by
+the application service. Private rooms (e.g. sending an email to someone) should not
+be exposed in this way, but should instead operate using normal invite/join semantics.
+Therefore, the ID conventions discussed below are only valid for public rooms which 
+expose room aliases.
+
+Matrix users may wish to join XMPP rooms (e.g. using XEP-0045) or IRC rooms. In both
+cases, these rooms can be expressed as URIs. For consistency, these "room" URIs 
+SHOULD be mapped in the same way as "user" URIs.
+
+::
+
+  GET /_matrix/app/v1/alias?uri=$url_encoded_uri
+  
+  Returns 200 OK:
+  {
+    alias: <complete room alias on local HS>
+  }
+  
+Event fields
+~~~~~~~~~~~~
+We recommend that any gatewayed events should include an ``external_url`` field
+in their content to provide a way for Matrix clients to link into the 'native'
+client from which the event originated. For instance, this could contain the
+message-ID for emails/nntp posts, or a link to a blog comment when gatewaying
+blog comment traffic in & out of matrix
+
+  
+Examples
+--------
+.. NOTE::
+  - User/Alias namespaces are subject to change depending on ID conventions.
+
+IRC
+~~~
+Pre-conditions:
+  - Server admin stores the AS token "T_a" on the home server.
+  - Home server has a token "T_h".
+  - Home server has the domain "hsdomain.com"
+
+1. Application service registration
+
+::
+  
+  AS -> HS: Registers itself with the home server
+  POST /register 
+  {
+   url: "https://someapp.com/matrix",
+   as_token: "T_a",
+   namespaces: {
+     users: [
+       {
+         "exclusive": true,
+         "regex": "@irc\.freenode\.net/.*"
+       }
+     ],
+     aliases: [
+       {
+         "exclusive": true,
+         "regex": "#irc\.freenode\.net/.*"
+       }
+     ]
+   }
+  }
+  
+  Returns 200 OK:
+  {
+    hs_token: "T_h"
+  }
+
+2. IRC user "Bob" says "hello?" on "#matrix" at timestamp 1421416883133:
+
+::  
+
+  - AS stores message as potential scrollback.
+  - Nothing happens as no Matrix users are in the room.
+ 
+3. Matrix user "@alice:hsdomain.com" wants to join "#matrix":
+
+::
+
+  User -> HS: Request to join "#irc.freenode.net/#matrix:hsdomain.com"
+  
+  HS -> AS: Room Query "#irc.freenode.net/#matrix:hsdomain.com"
+  GET /rooms/%23irc.freenode.net%2F%23matrix%3Ahsdomain.com?access_token=T_h
+  [Starts blocking]
+    AS -> HS: Creates room. Gets room ID "!aasaasasa:hsdomain.com".
+    AS -> HS: Sets room name to "#matrix".
+    AS -> HS: Sends message as ""@irc.freenode.net/Bob:hsdomain.com"
+      PUT /rooms/%21aasaasasa%3Ahsdomain.com/send/m.room.message
+                      ?access_token=T_a
+                      &user_id=%40irc.freenode.net%2FBob%3Ahsdomain.com
+                      &ts=1421416883133
+      {
+        body: "hello?"
+        msgtype: "m.text"
+      }
+    HS -> AS: User Query "@irc.freenode.net/Bob:hsdomain.com"
+      GET /users/%40irc.freenode.net%2FBob%3Ahsdomain.com?access_token=T_h
+      [Starts blocking]
+        AS -> HS: Creates user using CS API extension.
+          POST /register?access_token=T_a
+          {
+            type: "m.login.application_service",
+            user: "irc.freenode.net/Bob"
+          }
+        AS -> HS: Set user display name to "Bob".
+      [Finishes blocking]
+  [Finished blocking]
+  
+  - HS sends room information back to client.
+  
+4. @alice:hsdomain.com says "hi!" in this room:
+
+::
+
+  User -> HS: Send message "hi!" in room !aasaasasa:hsdomain.com
+  
+  - HS sends message.
+  - HS sees the room ID is in the AS namespace and pushes it to the AS.
+    
+  HS -> AS: Push event
+  PUT /transactions/1?access_token=T_h
+  {
+    events: [
+      {
+        content: {
+          body: "hi!",
+          msgtype: "m.text"
+        },
+        origin_server_ts: <generated by hs>,
+        user_id: "@alice:hsdomain.com",
+        room_id: "!aasaasasa:hsdomain.com",
+        type: "m.room.message"
+      }
+    ]
+  }
+  
+  - AS passes this through to IRC.
+  
+ 
+5. IRC user "Bob" says "what's up?" on "#matrix" at timestamp 1421418084816:
+
+::
+
+  IRC -> AS: "what's up?"
+  AS -> HS: Send message via CS API extension
+  PUT /rooms/%21aasaasasa%3Ahsdomain.com/send/m.room.message
+                  ?access_token=T_a
+                  &user_id=%40irc.freenode.net%2FBob%3Ahsdomain.com
+                  &ts=1421418084816
+  {
+    body: "what's up?"
+    msgtype: "m.text"
+  }
+  
+  - HS modifies the user_id and origin_server_ts on the event and sends it.

drafts/definitions.rst

@@ -5,7 +5,7 @@ Definitions
 
 # *Event* -- A JSON object that represents a piece of information to be
 distributed to the the room. The object includes a payload and metadata,
-including a `type` used to indicate what the payload is for and how to process
+including a ``type`` used to indicate what the payload is for and how to process
 them. It also includes one or more references to previous events.
 
 # *Event graph* -- Events and their references to previous events form a
@@ -13,7 +13,7 @@ directed acyclic graph. All events must be a descendant of the first event in a
 room, except for a few special circumstances.
 
 # *State event* -- A state event is an event that has a non-null string valued
-`state_key` field. It may also include a `prev_state` key referencing exactly
+`state_key` field. It may also include a ``prev_state`` key referencing exactly
 one state event with the same type and state key, in the same event graph.
 
 # *State tree* -- A state tree is a tree formed by a collection of state events

drafts/erik-model.rst

@@ -1,4 +1,7 @@
-This is a standalone description of the data architecture of Synapse.  There is a lot of overlap with the currennt specification, so it has been split out here for posterity.  Hopefully all the important bits have been merged into the relevant places in the main spec.
+This is a standalone description of the data architecture of Synapse. There is a
+lot of overlap with the current specification, so it has been split out here for
+posterity. Hopefully all the important bits have been merged into the relevant
+places in the main spec.
 
 
 Model

drafts/general_api.rst

@@ -555,7 +555,7 @@ signature. Requesting the "raw" federation event will have to return these keys.
 
 Account Management API ``[Draft]``
 ----------------------------------
-The registration and login APIs in v2 do not support specifying device IDs. In v2,
+The registration and login APIs in v1 do not support specifying device IDs. In v2,
 this will become *mandatory* when sending your initial request. Access tokens will
 be scoped per device, so using the same device ID twice when logging in will 
 clobber the old access token.
@@ -810,6 +810,11 @@ Notes:
 
 Presence API ``[Draft]``
 ------------------------
+
+.. FIXME
+  this seems to be ignoring activity timers entirely, which were present on
+  the planning etherpad and are present in the actual HTTP API. Needs attention.
+
 The goals of presence are to:
 
 - Let other users know if someone is "online".
@@ -817,22 +822,23 @@ The goals of presence are to:
 - Let other users know specific status information (e.g. "In a Meeting").
 
 "Online" state can be detected by inspecting when the last time the client made
-a request to the server. This could be any request, or a specific kind of request.
+a request to the server. This could be any request, or a specific kind of 
-For connection-orientated protocols, detecting "online" state can be determined by
+request. For connection-orientated protocols, detecting "online" state can be 
-the state of this connection stream. For HTTP, this can be detected via requests
+determined by the state of this connection stream. For HTTP, this can be 
-to the event stream.
+detected via requests to the event stream.
 
 Online state is separate from letting other users know if someone is *likely to
-respond* to messages. This introduces the concept of an "idle" flag, which is
+respond* to messages. This introduces the concept of being "idle", which is
-set when the user has not done any "interaction" with the app. The definition of
+when the user has not done any "interaction" with the app for a while. The 
-"interaction" varies based on the app, so it is up to the app to set this "idle"
+definition of "interaction" and "for a while" varies based on the app, so it is
-flag.
+up to the app to set when the user is idle.
-
+
-Letting users know specific status information can be achieved via the same method
+Letting users know specific status information can be achieved via the same 
-as v1. Status information should be scoped per *user* and not device as determining
+method as v1. Status information should be scoped per *user* and not device as 
-a union algorithm between statuses is nonsensical. Passing status information per
+determining a union algorithm between statuses is nonsensical. Passing status 
-device to all other users just redirects the union problem to the client, which
+information per device to all other users just redirects the union problem to 
-will commonly be presenting this information as an icon alongside the user.
+the client, which will commonly be presenting this information as an icon 
+alongside the user.
 
 When a client hits the event stream, the home server can treat the user as 
 "online". This behaviour should be able to be overridden to avoid flicker 
@@ -841,11 +847,11 @@ appear offline > goes into a tunnel > server times out > device regains
 connection and hits the event stream forcing the device online before the
 "appear offline" state can be set). When the client has not hit the event 
 stream for a certain period of time, the home server can treat the user as 
-"offline". 
+"offline". The user can also set a global *per-user* appear offline flag.
 
-The user should also be able to set their presence via a direct API, without 
+The user should also be able to set their presence state via a direct API, 
-having to hit the event stream. The home server will set a timer when the 
+without having to hit the event stream. The home server will set a timer when 
-connection ends, after which it will set that device to offline.
+the connection ends, after which it will set that device to offline.
 
 As the idle flag and online state is determined per device, there needs to be a
 union algorithm to merge these into a single state and flag per user, which will
@@ -859,22 +865,33 @@ Changing presence status:
 
 Inputs:
  - User ID
- - Presence status (online, away, busy, do not disturb, etc)
+ - Presence status (busy, do not disturb, in a meeting, etc)
-Outputs:
+Output:
  - None.
  
-Setting the idle flag:
+Setting presence state:
 
 Inputs:
  - User ID
- - Is idle
+ - Device ID
-Outputs:
+ - Presence state (online|idle|offline)
+Output:
+ - None.
+ 
+Setting global appear offline:
+
+Inputs:
+ - User ID
+ - Should appear offline (boolean)
+Output:
  - None.
  
 Extra parameters associated with the event stream:
 
 Inputs:
- - Presence state (online, appear offline)
+ - Presence state (online, idle, offline)
+Notes:
+ - Scoped per device just like the above API, e.g. from the access_token.
 
 
 Typing API ``[Final]``

drafts/macaroons_caveats.rst

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

drafts/media_repository.rst

@@ -1,76 +0,0 @@
-Media Repository
-================
-
-File uploading and downloading.
-
-HTTP API
---------
-
-Uploads are POSTed to a resource which returns a token which is used to GET
-the download.  Uploads are POSTed to the sender's local homeserver, but are
-downloaded from the recipient's local homeserver, which must thus first transfer
-the content from the origin homeserver using the same API (unless the origin
-and destination homeservers are the same).  The upload/download API is::
-
-    => POST /_matrix/media/v1/upload HTTP/1.1
-       Content-Type: <media-type>
-
-       <media>
-
-    <= HTTP/1.1 200 OK
-       Content-Type: application/json
-
-       { "content-uri": "mxc://<server-name>/<media-id>" }
-
-    => GET /_matrix/media/v1/download/<server-name>/<media-id> HTTP/1.1
-
-    <= HTTP/1.1 200 OK
-       Content-Type: <media-type>
-       Content-Disposition: attachment;filename=<upload-filename>
-
-       <media>
-
-Clients can get thumbnails by supplying a desired width and height and
-thumbnailing method::
-
-    => GET /_matrix/media/v1/thumbnail/<server_name>
-            /<media-id>?width=<w>&height=<h>&method=<m> HTTP/1.1
-
-    <= HTTP/1.1 200 OK
-       Content-Type: image/jpeg or image/png
-
-       <thumbnail>
-
-The thumbnail methods are "crop" and "scale". "scale" trys to return an
-image where either the width or the height is smaller than the requested
-size. The client should then scale and letterbox the image if it needs to
-fit within a given rectangle. "crop" trys to return an image where the
-width and height are close to the requested size and the aspect matches
-the requested size. The client should scale the image if it needs to fit
-within a given rectangle.
-
-Homeservers may generate thumbnails for content uploaded to remote
-homeservers themselves or may rely on the remote homeserver to thumbnail
-the content. Homeservers may return thumbnails of a different size to that
-requested. However homeservers should provide extact matches where reasonable.
-
-Security
---------
-
-Clients may try to upload very large files. Homeservers should not store files
-that are too large and should not serve them to clients.
-
-Clients may try to upload very large images. Homeservers should not attempt to
-generate thumbnails for images that are too large.
-
-Remote homeservers may host very large files or images. Homeserver should not
-proxy or thumbnail large files or images from remote homeservers.
-
-Clients may try to upload a large number of files. Homeservers should limit the
-number and total size of media that can be uploaded by clients.
-
-Clients may try to access a large number of remote files through a homeserver.
-Homeservers should restrict the number and size of remote files that it caches.
-
-Clients or remote homeservers may try to upload malicious files targeting
-vunerabilities in either the homeserver thumbnailing or the client decoders.

drafts/model/protocol_examples.rst

@@ -32,7 +32,7 @@ Content-Type: application/json
   }
 
 HTTP/1.1 200 OK
-...
+
 
 ======================================
 

drafts/object_model.rst

@@ -1,6 +1,5 @@
-
+..TODO
-
+  What are the start & end tokens doing here?!
-
 
 ::
 

drafts/pstn_gatewaying.txt

@@ -0,0 +1,48 @@
+Gatewaying to the PSTN via Matrix Application Services
+======================================================
+
+Matrix Application Services (AS) provides a way for PSTN users to interact
+with Matrix via an AS acting as a gateway. Each PSTN user is represented as a
+virtual user on a specific homeserver maintained by the AS. Typically the AS
+is provisioned on a well-known AS-supplier HS (e.g. matrix.openmarket.com) or
+is a service provisioned on the user's local HS.
+
+In either scenario, the AS maintains virtual users of form
+@.tel.e164:homeserver. These are lazily created (as per the AS spec) when
+matrix users try to contact a user id of form @.tel.*:homeserver, or when the
+AS needs to inject traffic into the HS on behalf of the PSTN user. The reason
+for these being a visible virtual user rather than an invisible user or an
+invisible sniffing AS is because they do represent real physical 3rd party
+endpoints in the PSTN, and need to be able to send return messages.
+
+Communication with an actual PSTN user happens in a normal Matrix room, which
+for 1:1 matrix<->pstn contact will typically store all conversation history
+with that user. On first contact, the matrix user invites the virtual user
+into the room (or vice versa). In the event of switching to another AS-enabled
+HS, the matrix user would kick the old AS and invite the new one. In the event
+of needing loadbalancing between two SMS gateways (for instance), the user
+would set visibility flags (TODO: specify per-message ACLs, or use crypto to
+only sign messages so they're visible to certain other users?) to adjust which
+virtual AS users could see which messages in the room.
+
+For group chat, one or more AS virtual users may be invited to a group chat,
+where-upon they will relay all the traffic in that group chat through to their
+PSTN counterpart (and vice versa). This behaviour requires no additional
+functionality beyond that required to support 1:1 chat.
+
+When contacting a user, Matrix clients should check whether a given E.164
+number is already mapped to a real Matrix user by querying the identity
+servers (or subscribing to identity updates for a given E.164 number. TODO: ID
+server subscriptions). If the E.164 number has a validated mapping in the ID
+server to a Matrix ID, then this target ID should be used instead of
+contacting the virtual user.
+
+It's likely that PSTN gateway ASes will need to charge the end-user for use of
+the gateway. The AS must therefore track credit per matrix ID it interacts
+with, and stop gatewaying as desired once credit is exhausted. The task of
+extracting credit from the end-user and adding it to the AS is not covered by
+the Matrix specification.
+
+For SMS routing, options are:
+ * Terminate traffic only (from a shared shortcode originator)
+ * Two-way traffic via a VMN. To save allocating huge numbers of VMNs to Matrix users, the VMN can be allocated from a pool such that each {caller,callee} tuple is unique (but the caller number will only work from that specific callee).

drafts/typing_notifications.rst

@@ -1,57 +0,0 @@
-Typing Notifications
-====================
-
-Client APIs
------------
-
-To set "I am typing for the next N msec"::
-  PUT .../rooms/:room_id/typing/:user_id
-  Content:  { "typing": true, "timeout": N }
-  # timeout is in msec; I suggest no more than 20 or 30 seconds
-
-This should be re-sent by the client to continue informing the server the user
-is still typing; I suggest a safety margin of 5 seconds before the expected
-timeout runs out. Just keep declaring a new timeout, it will replace the old
-one.
-
-To set "I am no longer typing"::
-  PUT ../rooms/:room_id/typing/:user_id
-  Content: { "typing": false }
-
-Client Events
--------------
-
-All room members will receive an event on the event stream::
-
-  {
-    "type": "m.typing",
-    "room_id": "!room-id-here:matrix.org",
-    "content": {
-      "user_ids": ["list of", "every user", "who is", "currently typing"]
-    }
-  }
-
-The client must use this list to *REPLACE* its knowledge of every user who is
-currently typing. The reason for this is that the server DOES NOT remember
-users who are not currently typing, as that list gets big quickly. The client
-should mark as not typing, any user ID who is not in that list.
-
-Server APIs
------------
-
-Servers will emit EDUs in the following form::
-
-  {
-    "type": "m.typing",
-    "content": {
-      "room_id": "!room-id-here:matrix.org",
-      "user_id": "@user-id-here:matrix.org",
-      "typing": true/false,
-    }
-  }
-
-Server EDUs don't (currently) contain timing information; it is up to
-originating HSes to ensure they eventually send "stop" notifications.
-
-((This will eventually need addressing, as part of the wider typing/presence
-timer addition work))

event-schemas/README.md

@@ -0,0 +1,13 @@
+Testing a schema
+----------------
+There are [many](http://json-schema.org/implementations.html) JSON Schema
+validators you can use to validate incoming events. Not all of them support
+JSON Schema v4, and some of them have bugs which prevent ``$ref`` from being
+resolved correctly. For basic CLI testing, we recommend and have verified they
+work with the Node.js package [z-schema](https://github.com/zaggino/z-schema):
+```
+ $ npm install -g z-schema
+ $ z-schema schema/v1/m.room.message examples/v1/m.room.message_m.text
+ schema validation passed
+ json #1 validation passed
+```

event-schemas/check.sh

@@ -0,0 +1,16 @@
+#!/bin/bash -e
+# Runs z-schema over all of the schema files (looking for matching examples)
+find schema/v1/m.* | while read line
+do
+    split_path=(${line///// })
+    event_type=(${split_path[2]})
+    echo "Checking $event_type"
+    echo "--------------------"
+    # match exact name or exact name with a #<something>
+    find examples/v1 -name $event_type -o -name "$event_type#*" | while read exline
+    do
+        echo "    against $exline"
+        # run z-schema: because of bash -e if this fails we bail with exit code 1
+        z-schema schema/v1/$event_type $exline
+    done
+done

event-schemas/check_examples.py

@@ -0,0 +1,76 @@
+#! /usr/bin/env python
+
+import sys
+import json
+import os
+import traceback
+
+
+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_example_file(examplepath, schemapath):
+    with open(examplepath) as f:
+        example = yaml.load(f)
+
+    with open(schemapath) as f:
+        schema = yaml.load(f)
+
+    fileurl = "file://" + os.path.abspath(schemapath)
+
+    print ("Checking schema for: %r %r" % (examplepath, schemapath))
+    # Setting the 'id' tells jsonschema where the file is so that it
+    # can correctly resolve relative $ref references in the schema
+    schema['id'] = fileurl
+    try:
+        jsonschema.validate(example, schema)
+    except Exception as e:
+        raise ValueError("Error validating JSON schema for %r %r" % (
+            examplepath, schemapath
+        ), e)
+
+
+def check_example_dir(exampledir, schemadir):
+    errors = []
+    for root, dirs, files in os.walk(exampledir):
+        for filename in files:
+            if filename.startswith("."):
+                # Skip over any vim .swp files.
+                continue
+            examplepath = os.path.join(root, filename)
+            schemapath = examplepath.replace(exampledir, schemadir)
+            try:
+                check_example_file(examplepath, schemapath)
+            except Exception as e:
+                errors.append(sys.exc_info())
+    for (exc_type, exc_value, exc_trace) in errors:
+        traceback.print_exception(exc_type, exc_value, exc_trace)
+    if errors:
+        raise ValueError("Error validating examples")
+
+if __name__ == '__main__':
+    try:
+        check_example_dir("examples", "schema")
+    except:
+        sys.exit(1)

event-schemas/examples/v1/m.call.answer

@@ -0,0 +1,17 @@
+{
+  "age": 242352,
+  "content": {
+    "version" : 0,
+    "call_id": "12345",
+    "lifetime": 60000,
+    "answer": {
+      "type" : "answer",
+      "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
+    }
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.call.answer",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.call.candidates

@@ -0,0 +1,19 @@
+{
+  "age": 242352,
+  "content": {
+    "version" : 0,
+    "call_id": "12345",
+    "candidates": [
+      {
+        "sdpMid": "audio",
+        "sdpMLineIndex": 0,
+        "candidate": "candidate:863018703 1 udp 2122260223 10.9.64.156 43670 typ host generation 0"
+      }
+    ]
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.call.candidates",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.call.hangup

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "version" : 0,
+    "call_id": "12345"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.call.hangup",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.call.invite

@@ -0,0 +1,17 @@
+{
+  "age": 242352,
+  "content": {
+    "version" : 0,
+    "call_id": "12345",
+    "lifetime": 60000,
+    "offer": {
+      "type" : "offer",
+      "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]"
+    }
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.call.invite",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.presence

@@ -0,0 +1,10 @@
+{
+  "content": {
+    "avatar_url": "mxc://localhost:wefuiwegh8742w",
+    "last_active_ago": 2478593,
+    "presence": "online",
+    "user_id": "@example:localhost"
+  },
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.presence"
+}

event-schemas/examples/v1/m.receipt

@@ -0,0 +1,13 @@
+{
+    "type": "m.receipt",
+    "room_id": "!KpjVgQyZpzBwvMBsnT:matrix.org",
+    "content": {
+        "$1435641916114394fHBLK:matrix.org": {
+            "m.read": {
+                "@rikj:jki.re": {
+                    "ts": 1436451550453
+                }
+            }
+        }
+    }
+}

event-schemas/examples/v1/m.room.aliases

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "aliases": ["#somewhere:localhost", "#another:localhost"]
+  },
+  "state_key": "localhost",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.aliases",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.canonical_alias

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "alias": "#somewhere:localhost"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.canonical_alias",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.create

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "creator": "@example:localhost"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.create",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.history_visibility

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "history_visibility": "shared"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.history_visibility",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.join_rules

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "join_rule": "public"
+  },
+  "state_key": "",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.join_rules",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.member

@@ -0,0 +1,21 @@
+{
+  "age": 242352,
+  "content": {
+    "membership": "join",
+    "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
+    "displayname": "Alice Margatroid",
+    "third_party_invite": {
+        "token": "pc98",
+        "public_key": "abc123",
+        "key_validity_url": "https://magic.forest/verifykey",
+        "signature": "q1w2e3",
+        "sender": "@zun:zun.soft"
+    }
+  },
+  "state_key": "@alice:localhost",
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.member",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.message#m.audio

@@ -0,0 +1,18 @@
+{
+  "age": 146,
+  "content": {
+    "body": "Bee Gees - Stayin' Alive",
+    "url": "mxc://localhost/ffed755USFFxlgbQYZGtryd",
+    "info": {
+      "duration": 2140786,
+      "size": 1563685,
+      "mimetype": "audio/mpeg"
+    },
+    "msgtype": "m.audio"
+  },
+  "event_id": "$143273582443PhrSn:localhost",
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
+  "type": "m.room.message",
+  "user_id": "@example:localhost"
+} 

event-schemas/examples/v1/m.room.message#m.emote

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "body": "thinks this is an example emote",
+    "msgtype": "m.emote"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.message",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.message#m.file

@@ -0,0 +1,18 @@
+{
+  "age": 146,
+  "content": {
+    "body": "something-important.doc",
+    "filename": "something-important.doc",
+    "info": {
+      "mimetype": "application/msword",
+      "size": 46144
+    },
+    "msgtype": "m.file",
+    "url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe"
+  },
+  "event_id": "$143273582443PhrSn:localhost",
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
+  "type": "m.room.message",
+  "user_id": "@example:localhost"
+} 

event-schemas/examples/v1/m.room.message#m.image

@@ -0,0 +1,19 @@
+{
+  "age": 242352,
+  "content": {
+    "body": "filename.jpg",
+    "info": {
+        "h": 398,
+        "w": 394,
+        "mimetype": "image/jpeg",
+        "size": 31037
+    },
+    "url": "mxc://localhost/JWEIFJgwEIhweiWJE",
+    "msgtype": "m.image"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.message",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.message#m.location

@@ -0,0 +1,20 @@
+{
+  "age": 146,
+  "content": {
+    "body": "Big Ben, London, UK",
+    "geo_uri": "geo:51.5008,0.1247",
+    "thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe",
+    "thumbnail_info": {
+      "mimetype": "image/jpeg",
+      "size": 46144,
+      "w": 300,
+      "h": 300
+    },
+    "msgtype": "m.location"
+  },
+  "event_id": "$143273582443PhrSn:localhost",
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
+  "type": "m.room.message",
+  "user_id": "@example:localhost"
+} 

event-schemas/examples/v1/m.room.message#m.notice

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "body": "This is an example notice",
+    "msgtype": "m.notice"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.message",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.message#m.text

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "body": "This is an example text message",
+    "msgtype": "m.text"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.message",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}

event-schemas/examples/v1/m.room.message#m.video

@@ -0,0 +1,27 @@
+{
+  "age": 146,
+  "content": {
+    "body": "Gangnam Style",
+    "url": "mxc://localhost/a526eYUSFFxlgbQYZmo442",
+    "info": {
+      "thumbnail_url": "mxc://localhost/FHyPlCeYUSFFxlgbQYZmoEoe",
+      "thumbnail_info": {
+        "mimetype": "image/jpeg",
+        "size": 46144,
+        "w": 300,
+        "h": 300
+      },
+      "w": 480,
+      "h": 320,
+      "duration": 2140786,
+      "size": 1563685,
+      "mimetype": "video/mp4"
+    },
+    "msgtype": "m.video"
+  },
+  "event_id": "$143273582443PhrSn:localhost",
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:localhost",
+  "type": "m.room.message",
+  "user_id": "@example:localhost"
+} 

event-schemas/examples/v1/m.room.message.feedback

@@ -0,0 +1,12 @@
+{
+  "age": 242352,
+  "content": {
+    "type": "delivered",
+    "target_event_id": "$WEIGFHFW:localhost"
+  },
+  "origin_server_ts": 1431961217939,
+  "event_id": "$WLGTSEFSEF:localhost",
+  "type": "m.room.message.feedback",
+  "room_id": "!Cuyf34gef24t:localhost",
+  "user_id": "@example:localhost"
+}