summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorErik Johnston <erik@matrix.org>2014-10-17 21:02:16 +0100
committerErik Johnston <erik@matrix.org>2014-10-17 21:02:16 +0100
commit449739e6a364759a86f73417626af49d6a794e3d (patch)
tree04b2f39c91ec6098ffe3b380442787ac3ce2908f /docs
parentMerge branch 'release-v0.3.4' of github.com:matrix-org/synapse (diff)
parentCheck that we have auth headers and fail nicely (diff)
downloadsynapse-449739e6a364759a86f73417626af49d6a794e3d.tar.xz
Merge branch 'release-v0.4.0' of github.com:matrix-org/synapse
Diffstat (limited to 'docs')
-rw-r--r--docs/README.rst6
-rw-r--r--docs/client-server/howto.rst636
-rw-r--r--docs/client-server/model/presence.rst100
-rw-r--r--docs/client-server/swagger_matrix/api-docs46
-rw-r--r--docs/client-server/swagger_matrix/api-docs-directory85
-rw-r--r--docs/client-server/swagger_matrix/api-docs-events247
-rw-r--r--docs/client-server/swagger_matrix/api-docs-login120
-rw-r--r--docs/client-server/swagger_matrix/api-docs-presence164
-rw-r--r--docs/client-server/swagger_matrix/api-docs-profile122
-rw-r--r--docs/client-server/swagger_matrix/api-docs-registration120
-rw-r--r--docs/client-server/swagger_matrix/api-docs-rooms977
-rw-r--r--docs/freenode.txt1
-rw-r--r--docs/human-id-rules.rst79
-rw-r--r--docs/implementation-notes/documentation_style.rst43
-rw-r--r--docs/server-server/signing.rst151
-rw-r--r--docs/specification.rst2306
16 files changed, 157 insertions, 5046 deletions
diff --git a/docs/README.rst b/docs/README.rst
new file mode 100644
index 0000000000..3012da8b19
--- /dev/null
+++ b/docs/README.rst
@@ -0,0 +1,6 @@
+All matrix-generic documentation now lives in its own project at
+
+github.com/matrix-org/matrix-doc.git
+
+Only Synapse implementation-specific documentation lives here now
+(together with some older stuff will be shortly migrated over to matrix-doc)
diff --git a/docs/client-server/howto.rst b/docs/client-server/howto.rst
deleted file mode 100644
index ec941edddd..0000000000
--- a/docs/client-server/howto.rst
+++ /dev/null
@@ -1,636 +0,0 @@
-.. TODO kegan
-  Room config (specifically: message history,
-  public rooms). /register seems super simplistic compared to /login, maybe it
-  would be better if /register used the same technique as /login? /register should
-  be "user" not "user_id".
-
-
-How to use the client-server API
-================================
-
-This guide focuses on how the client-server APIs *provided by the reference 
-home server* can be used. Since this is specific to a home server 
-implementation, there may be variations in relation to registering/logging in
-which are not covered in extensive detail in this guide.
-
-If you haven't already, get a home server up and running on 
-``http://localhost:8008``.
-
-
-Accounts
-========
-Before you can send and receive messages, you must **register** for an account. 
-If you already have an account, you must **login** into it.
-
-`Try out the fiddle`__
-
-.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/register_login
-
-Registration
-------------
-The aim of registration is to get a user ID and access token which you will need
-when accessing other APIs::
-
-    curl -XPOST -d '{"user_id":"example", "password":"wordpass"}' "http://localhost:8008/_matrix/client/api/v1/register"
-
-    {
-        "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.AqdSzFmFYrLrTmteXc", 
-        "home_server": "localhost", 
-        "user_id": "@example:localhost"
-    }
-
-NB: If a ``user_id`` is not specified, one will be randomly generated for you. 
-If you do not specify a ``password``, you will be unable to login to the account
-if you forget the ``access_token``.
-
-Implementation note: The matrix specification does not enforce how users 
-register with a server. It just specifies the URL path and absolute minimum 
-keys. The reference home server uses a username/password to authenticate user,
-but other home servers may use different methods.
-
-Login
------
-The aim when logging in is to get an access token for your existing user ID::
-
-    curl -XGET "http://localhost:8008/_matrix/client/api/v1/login"
-
-    {
-        "flows": [
-            {
-                "type": "m.login.password"
-            }
-        ]
-    }
-
-    curl -XPOST -d '{"type":"m.login.password", "user":"example", "password":"wordpass"}' "http://localhost:8008/_matrix/client/api/v1/login"
-
-    {
-        "access_token": "QGV4YW1wbGU6bG9jYWxob3N0.vRDLTgxefmKWQEtgGd", 
-        "home_server": "localhost", 
-        "user_id": "@example:localhost"
-    }
-    
-Implementation note: Different home servers may implement different methods for 
-logging in to an existing account. In order to check that you know how to login 
-to this home server, you must perform a ``GET`` first and make sure you 
-recognise the login type. If you do not know how to login, you can 
-``GET /login/fallback`` which will return a basic webpage which you can use to 
-login. The reference home server implementation support username/password login,
-but other home servers may support different login methods (e.g. OAuth2).
-
-
-Communicating
-=============
-
-In order to communicate with another user, you must **create a room** with that 
-user and **send a message** to that room. 
-
-`Try out the fiddle`__
-
-.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/create_room_send_msg
-
-Creating a room
----------------
-If you want to send a message to someone, you have to be in a room with them. To
-create a room::
-
-    curl -XPOST -d '{"room_alias_name":"tutorial"}' "http://localhost:8008/_matrix/client/api/v1/createRoom?access_token=YOUR_ACCESS_TOKEN"
-
-    {
-        "room_alias": "#tutorial:localhost", 
-        "room_id": "!CvcvRuDYDzTOzfKKgh:localhost"
-    }
-    
-The "room alias" is a human-readable string which can be shared with other users
-so they can join a room, rather than the room ID which is a randomly generated
-string. You can have multiple room aliases per room.
-
-.. TODO(kegan)
-  How to add/remove aliases from an existing room.
-    
-
-Sending messages
-----------------
-You can now send messages to this room::
-
-    curl -XPOST -d '{"msgtype":"m.text", "body":"hello"}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/send/m.room.message?access_token=YOUR_ACCESS_TOKEN"
-    
-    {
-        "event_id": "YUwRidLecu"
-    }
-    
-The event ID returned is a unique ID which identifies this message.
-    
-NB: There are no limitations to the types of messages which can be exchanged.
-The only requirement is that ``"msgtype"`` is specified. The Matrix 
-specification outlines the following standard types: ``m.text``, ``m.image``,
-``m.audio``, ``m.video``, ``m.location``, ``m.emote``. See the specification for
-more information on these types.
-
-Users and rooms
-===============
-
-Each room can be configured to allow or disallow certain rules. In particular,
-these rules may specify if you require an **invitation** from someone already in
-the room in order to **join the room**. In addition, you may also be able to 
-join a room **via a room alias** if one was set up.
-
-`Try out the fiddle`__
-
-.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/room_memberships
-
-Inviting a user to a room
--------------------------
-You can directly invite a user to a room like so::
-
-    curl -XPOST -d '{"user_id":"@myfriend:localhost"}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/invite?access_token=YOUR_ACCESS_TOKEN"
-    
-This informs ``@myfriend:localhost`` of the room ID 
-``!CvcvRuDYDzTOzfKKgh:localhost`` and allows them to join the room.
-
-Joining a room via an invite
-----------------------------
-If you receive an invite, you can join the room::
-
-    curl -XPOST -d '{}' "http://localhost:8008/_matrix/client/api/v1/rooms/%21CvcvRuDYDzTOzfKKgh%3Alocalhost/join?access_token=YOUR_ACCESS_TOKEN"
-    
-NB: Only the person invited (``@myfriend:localhost``) can change the membership
-state to ``"join"``. Repeatedly joining a room does nothing.
-
-Joining a room via an alias
----------------------------
-Alternatively, if you know the room alias for this room and the room config 
-allows it, you can directly join a room via the alias::
-
-    curl -XPOST -d '{}' "http://localhost:8008/_matrix/client/api/v1/join/%23tutorial%3Alocalhost?access_token=YOUR_ACCESS_TOKEN"
-    
-    {
-        "room_id": "!CvcvRuDYDzTOzfKKgh:localhost"
-    }
-    
-You will need to use the room ID when sending messages, not the room alias.
-
-NB: If the room is configured to be an invite-only room, you will still require
-an invite in order to join the room even though you know the room alias. As a
-result, it is more common to see a room alias in relation to a public room, 
-which do not require invitations.
-
-Getting events
-==============
-An event is some interesting piece of data that a client may be interested in. 
-It can be a message in a room, a room invite, etc. There are many different ways
-of getting events, depending on what the client already knows.
-
-`Try out the fiddle`__
-
-.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/event_stream
-
-Getting all state
------------------
-If the client doesn't know any information on the rooms the user is 
-invited/joined on, they can get all the user's state for all rooms::
-
-    curl -XGET "http://localhost:8008/_matrix/client/api/v1/initialSync?access_token=YOUR_ACCESS_TOKEN"
-    
-    {
-        "end": "s39_18_0", 
-        "presence": [
-            {
-                "content": {
-                    "last_active_ago": 1061436, 
-                    "user_id": "@example:localhost"
-                }, 
-                "type": "m.presence"
-            }
-        ], 
-        "rooms": [
-            {
-                "membership": "join", 
-                "messages": {
-                    "chunk": [
-                        {
-                            "content": {
-                                "@example:localhost": 10, 
-                                "default": 0
-                            }, 
-                            "event_id": "wAumPSTsWF", 
-                            "required_power_level": 10, 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "", 
-                            "ts": 1409665585188, 
-                            "type": "m.room.power_levels", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "join_rule": "public"
-                            }, 
-                            "event_id": "jrLVqKHKiI", 
-                            "required_power_level": 10, 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "", 
-                            "ts": 1409665585188, 
-                            "type": "m.room.join_rules", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "level": 10
-                            }, 
-                            "event_id": "WpmTgsNWUZ", 
-                            "required_power_level": 10, 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "", 
-                            "ts": 1409665585188, 
-                            "type": "m.room.add_state_level", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "level": 0
-                            }, 
-                            "event_id": "qUMBJyKsTQ", 
-                            "required_power_level": 10, 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "", 
-                            "ts": 1409665585188, 
-                            "type": "m.room.send_event_level", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "ban_level": 5, 
-                                "kick_level": 5
-                            }, 
-                            "event_id": "YAaDmKvoUW", 
-                            "required_power_level": 10, 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "", 
-                            "ts": 1409665585188, 
-                            "type": "m.room.ops_levels", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "avatar_url": null, 
-                                "displayname": null, 
-                                "membership": "join"
-                            }, 
-                            "event_id": "RJbPMtCutf", 
-                            "membership": "join", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "@example:localhost", 
-                            "ts": 1409665586730, 
-                            "type": "m.room.member", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "body": "hello", 
-                                "hsob_ts": 1409665660439, 
-                                "msgtype": "m.text"
-                            }, 
-                            "event_id": "YUwRidLecu", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "ts": 1409665660439, 
-                            "type": "m.room.message", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "membership": "invite"
-                            }, 
-                            "event_id": "YjNuBKnPsb", 
-                            "membership": "invite", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "@myfriend:localhost", 
-                            "ts": 1409666426819, 
-                            "type": "m.room.member", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "avatar_url": null, 
-                                "displayname": null, 
-                                "membership": "join", 
-                                "prev": "join"
-                            }, 
-                            "event_id": "KWwdDjNZnm", 
-                            "membership": "join", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "@example:localhost", 
-                            "ts": 1409666551582, 
-                            "type": "m.room.member", 
-                            "user_id": "@example:localhost"
-                        }, 
-                        {
-                            "content": {
-                                "avatar_url": null, 
-                                "displayname": null, 
-                                "membership": "join"
-                            }, 
-                            "event_id": "JFLVteSvQc", 
-                            "membership": "join", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "@example:localhost", 
-                            "ts": 1409666587265, 
-                            "type": "m.room.member", 
-                            "user_id": "@example:localhost"
-                        }
-                    ], 
-                    "end": "s39_18_0", 
-                    "start": "t1-11_18_0"
-                }, 
-                "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                "state": [
-                    {
-                        "content": {
-                            "creator": "@example:localhost"
-                        }, 
-                        "event_id": "dMUoqVTZca", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.create", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "@example:localhost": 10, 
-                            "default": 0
-                        }, 
-                        "event_id": "wAumPSTsWF", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.power_levels", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "join_rule": "public"
-                        }, 
-                        "event_id": "jrLVqKHKiI", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.join_rules", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "level": 10
-                        }, 
-                        "event_id": "WpmTgsNWUZ", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.add_state_level", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "level": 0
-                        }, 
-                        "event_id": "qUMBJyKsTQ", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.send_event_level", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "ban_level": 5, 
-                            "kick_level": 5
-                        }, 
-                        "event_id": "YAaDmKvoUW", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.ops_levels", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "membership": "invite"
-                        }, 
-                        "event_id": "YjNuBKnPsb", 
-                        "membership": "invite", 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "@myfriend:localhost", 
-                        "ts": 1409666426819, 
-                        "type": "m.room.member", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "avatar_url": null, 
-                            "displayname": null, 
-                            "membership": "join"
-                        }, 
-                        "event_id": "JFLVteSvQc", 
-                        "membership": "join", 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "@example:localhost", 
-                        "ts": 1409666587265, 
-                        "type": "m.room.member", 
-                        "user_id": "@example:localhost"
-                    }
-                ]
-            }
-        ]
-    }
-    
-This returns all the room information the user is invited/joined on, as well as
-all of the presences relevant for these rooms. This can be a LOT of data. You
-may just want the most recent event for each room. This can be achieved by 
-applying query parameters to ``limit`` this request::
-
-    curl -XGET "http://localhost:8008/_matrix/client/api/v1/initialSync?limit=1&access_token=YOUR_ACCESS_TOKEN"
-    
-    {
-        "end": "s39_18_0", 
-        "presence": [
-            {
-                "content": {
-                    "last_active_ago": 1279484, 
-                    "user_id": "@example:localhost"
-                }, 
-                "type": "m.presence"
-            }
-        ], 
-        "rooms": [
-            {
-                "membership": "join", 
-                "messages": {
-                    "chunk": [
-                        {
-                            "content": {
-                                "avatar_url": null, 
-                                "displayname": null, 
-                                "membership": "join"
-                            }, 
-                            "event_id": "JFLVteSvQc", 
-                            "membership": "join", 
-                            "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                            "state_key": "@example:localhost", 
-                            "ts": 1409666587265, 
-                            "type": "m.room.member", 
-                            "user_id": "@example:localhost"
-                        }
-                    ], 
-                    "end": "s39_18_0", 
-                    "start": "t10-30_18_0"
-                }, 
-                "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                "state": [
-                    {
-                        "content": {
-                            "creator": "@example:localhost"
-                        }, 
-                        "event_id": "dMUoqVTZca", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.create", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "@example:localhost": 10, 
-                            "default": 0
-                        }, 
-                        "event_id": "wAumPSTsWF", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.power_levels", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "join_rule": "public"
-                        }, 
-                        "event_id": "jrLVqKHKiI", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.join_rules", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "level": 10
-                        }, 
-                        "event_id": "WpmTgsNWUZ", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.add_state_level", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "level": 0
-                        }, 
-                        "event_id": "qUMBJyKsTQ", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.send_event_level", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "ban_level": 5, 
-                            "kick_level": 5
-                        }, 
-                        "event_id": "YAaDmKvoUW", 
-                        "required_power_level": 10, 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "", 
-                        "ts": 1409665585188, 
-                        "type": "m.room.ops_levels", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "membership": "invite"
-                        }, 
-                        "event_id": "YjNuBKnPsb", 
-                        "membership": "invite", 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "@myfriend:localhost", 
-                        "ts": 1409666426819, 
-                        "type": "m.room.member", 
-                        "user_id": "@example:localhost"
-                    }, 
-                    {
-                        "content": {
-                            "avatar_url": null, 
-                            "displayname": null, 
-                            "membership": "join"
-                        }, 
-                        "event_id": "JFLVteSvQc", 
-                        "membership": "join", 
-                        "room_id": "!MkDbyRqnvTYnoxjLYx:localhost", 
-                        "state_key": "@example:localhost", 
-                        "ts": 1409666587265, 
-                        "type": "m.room.member", 
-                        "user_id": "@example:localhost"
-                    }
-                ]
-            }
-        ]
-    }
-
-Getting live state
-------------------
-Once you know which rooms the client has previously interacted with, you need to
-listen for incoming events. This can be done like so::
-
-    curl -XGET "http://localhost:8008/_matrix/client/api/v1/events?access_token=YOUR_ACCESS_TOKEN"
-    
-    {
-        "chunk": [], 
-        "end": "s39_18_0", 
-        "start": "s39_18_0"
-    }
-    
-This will block waiting for an incoming event, timing out after several seconds.
-Even if there are no new events (as in the example above), there will be some
-pagination stream response keys. The client should make subsequent requests 
-using the value of the ``"end"`` key (in this case ``s39_18_0``) as the ``from`` 
-query parameter e.g. ``http://localhost:8008/_matrix/client/api/v1/events?access
-_token=YOUR_ACCESS_TOKEN&from=s39_18_0``. This value should be stored so when the 
-client reopens your app after a period of inactivity, you can resume from where 
-you got up to in the event stream. If it has been a long period of inactivity, 
-there may be LOTS of events waiting for the user. In this case, you may wish to 
-get all state instead and then resume getting live state from a newer end token.
-
-NB: The timeout can be changed by adding a ``timeout`` query parameter, which is
-in milliseconds. A timeout of 0 will not block.
-
-
-Example application
--------------------
-The following example demonstrates registration and login, live event streaming,
-creating and joining rooms, sending messages, getting member lists and getting 
-historical messages for a room. This covers most functionality of a messaging
-application.
-
-`Try out the fiddle`__
-
-.. __: http://jsfiddle.net/gh/get/jquery/1.8.3/matrix-org/synapse/tree/master/jsfiddles/example_app
diff --git a/docs/client-server/model/presence.rst b/docs/client-server/model/presence.rst
index 7e54505364..811bac3fab 100644
--- a/docs/client-server/model/presence.rst
+++ b/docs/client-server/model/presence.rst
@@ -1,103 +1,3 @@
-========
-Presence
-========
-
-A description of presence information and visibility between users.
-
-Overview
-========
-
-Each user has the concept of Presence information. This encodes a sense of the
-"availability" of that user, suitable for display on other user's clients.
-
-
-Presence Information
-====================
-
-The basic piece of presence information is an enumeration of a small set of
-state; such as "free to chat", "online", "busy", or "offline". The default state
-unless the user changes it is "online". Lower states suggest some amount of
-decreased availability from normal, which might have some client-side effect
-like muting notification sounds and suggests to other users not to bother them
-unless it is urgent. Equally, the "free to chat" state exists to let the user
-announce their general willingness to receive messages moreso than default.
-
-Home servers should also allow a user to set their state as "hidden" - a state
-which behaves as offline, but allows the user to see the client state anyway and
-generally interact with client features such as reading message history or
-accessing contacts in the address book.
-
-This basic state field applies to the user as a whole, regardless of how many
-client devices they have connected. The home server should synchronise this
-status choice among multiple devices to ensure the user gets a consistent
-experience.
-
-Idle Time
----------
-
-As well as the basic state field, the presence information can also show a sense
-of an "idle timer". This should be maintained individually by the user's
-clients, and the homeserver can take the highest reported time as that to
-report. Likely this should be presented in fairly coarse granularity; possibly
-being limited to letting the home server automatically switch from a "free to
-chat" or "online" mode into "idle".
-
-When a user is offline, the Home Server can still report when the user was last
-seen online, again perhaps in a somewhat coarse manner.
-
-Device Type
------------
-
-Client devices that may limit the user experience somewhat (such as "mobile"
-devices with limited ability to type on a real keyboard or read large amounts of
-text) should report this to the home server, as this is also useful information
-to report as "presence" if the user cannot be expected to provide a good typed
-response to messages.
-
-
-Presence List
-=============
-
-Each user's home server stores a "presence list" for that user. This stores a
-list of other user IDs the user has chosen to add to it (remembering any ACL
-Pointer if appropriate).
-
-To be added to a contact list, the user being added must grant permission. Once
-granted, both user's HS(es) store this information, as it allows the user who
-has added the contact some more abilities; see below. Since such subscriptions
-are likely to be bidirectional, HSes may wish to automatically accept requests
-when a reverse subscription already exists.
-
-As a convenience, presence lists should support the ability to collect users
-into groups, which could allow things like inviting the entire group to a new
-("ad-hoc") chat room, or easy interaction with the profile information ACL
-implementation of the HS.
-
-
-Presence and Permissions
-========================
-
-For a viewing user to be allowed to see the presence information of a target
-user, either
-
- * The target user has allowed the viewing user to add them to their presence
-   list, or
-
- * The two users share at least one room in common
-
-In the latter case, this allows for clients to display some minimal sense of
-presence information in a user list for a room.
-
-Home servers can also use the user's choice of presence state as a signal for
-how to handle new private one-to-one chat message requests. For example, it
-might decide:
-
-  "free to chat": accept anything
-  "online": accept from anyone in my addres book list
-  "busy": accept from anyone in this "important people" group in my address
-    book list
-
-
 API Efficiency
 ==============
 
diff --git a/docs/client-server/swagger_matrix/api-docs b/docs/client-server/swagger_matrix/api-docs
deleted file mode 100644
index a80b3bb342..0000000000
--- a/docs/client-server/swagger_matrix/api-docs
+++ /dev/null
@@ -1,46 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "apis": [
-    {
-      "path": "-login",
-      "description": "Login operations"
-    },
-    {
-      "path": "-registration",
-      "description": "Registration operations"
-    },
-    {
-      "path": "-rooms",
-      "description": "Room operations"
-    },
-    {
-      "path": "-profile",
-      "description": "Profile operations"
-    },
-    {
-      "path": "-presence",
-      "description": "Presence operations"
-    },
-    {
-      "path": "-events",
-      "description": "Event operations"
-    },
-    {
-      "path": "-directory",
-      "description": "Directory operations"
-    }
-  ],
-  "authorizations": {
-    "token": {
-      "scopes": []
-    }
-  },
-  "info": {
-    "title": "Matrix Client-Server API Reference",
-    "description": "This contains the client-server API for the reference implementation of the home server",
-    "termsOfServiceUrl": "http://matrix.org",
-    "license": "Apache 2.0",
-    "licenseUrl": "http://www.apache.org/licenses/LICENSE-2.0.html"
-  }
-}
diff --git a/docs/client-server/swagger_matrix/api-docs-directory b/docs/client-server/swagger_matrix/api-docs-directory
deleted file mode 100644
index ce12be8c96..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-directory
+++ /dev/null
@@ -1,85 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/directory",
-  "produces": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/directory/room/{roomAlias}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get the room ID corresponding to this room alias.",
-          "notes": "Volatile: This API is likely to change.",
-          "type": "DirectoryResponse",
-          "nickname": "get_room_id_for_alias",
-          "parameters": [
-            {
-              "name": "roomAlias",
-              "description": "The room alias.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "PUT",
-          "summary": "Create a new mapping from room alias to room ID.",
-          "notes": "Volatile: This API is likely to change.",
-          "type": "void",
-          "nickname": "add_room_alias",
-          "parameters": [
-            {
-              "name": "roomAlias",
-              "description": "The room alias to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The room ID to set.",
-              "required": true,
-              "type": "RoomAliasRequest",
-              "paramType": "body"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "DirectoryResponse": {
-      "id": "DirectoryResponse",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The fully-qualified room ID.",
-          "required": true
-        },
-        "servers": {
-          "type": "array",
-          "items": {
-            "$ref": "string"
-          },
-          "description": "A list of servers that know about this room.",
-          "required": true
-        }
-      }
-    },
-    "RoomAliasRequest": {
-      "id": "RoomAliasRequest",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The room ID to map the alias to.",
-          "required": true
-        }
-      }
-    }
-  }
-}
diff --git a/docs/client-server/swagger_matrix/api-docs-events b/docs/client-server/swagger_matrix/api-docs-events
deleted file mode 100644
index 1bdb9b034a..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-events
+++ /dev/null
@@ -1,247 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/events",
-  "produces": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/events",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Listen on the event stream",
-          "notes": "This can only be done by the logged in user. This will block until an event is received, or until the timeout is reached.",
-          "type": "PaginationChunk",
-          "nickname": "get_event_stream",
-          "parameters": [
-            {
-              "name": "from",
-              "description": "The token to stream from.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "timeout",
-              "description": "The maximum time in milliseconds to wait for an event.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            }
-          ]
-        }
-      ],
-      
-      "responseMessages": [
-        {
-          "code": 400,
-          "message": "Bad pagination token."
-        }
-      ]
-    },
-    {
-      "path": "/events/{eventId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get information about a single event.",
-          "notes": "Get information about a single event.",
-          "type": "Event",
-          "nickname": "get_event",
-          "parameters": [
-            {
-              "name": "eventId",
-              "description": "The event ID to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 404,
-              "message": "Event not found."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/initialSync",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get this user's current state.",
-          "notes": "Get this user's current state.",
-          "type": "InitialSyncResponse",
-          "nickname": "initial_sync",
-          "parameters": [
-            {
-              "name": "limit",
-              "description": "The maximum number of messages to return for each room.",
-              "type": "integer",
-              "paramType": "query",
-              "required": false
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/publicRooms",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a list of publicly visible rooms.",
-          "type": "PublicRoomsPaginationChunk",
-          "nickname": "get_public_room_list"
-        }
-      ]
-    }
-  ],
-  "models": {
-    "PaginationChunk": {
-      "id": "PaginationChunk",
-      "properties": {
-        "start": {
-          "type": "string",
-          "description": "A token which correlates to the first value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "end": {
-          "type": "string",
-          "description": "A token which correlates to the last value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "chunk": {
-          "type": "array",
-          "description": "An array of events.",
-          "required": true,
-          "items": {
-            "$ref": "Event"
-          }
-        }
-      }
-    },
-    "Event": {
-      "id": "Event",
-      "properties": {
-        "event_id": {
-          "type": "string",
-          "description": "An ID which uniquely identifies this event.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The room in which this event occurred.",
-          "required": true
-        }
-      }
-    },
-    "PublicRoomInfo": {
-      "id": "PublicRoomInfo",
-      "properties": {
-        "aliases": {
-          "type": "array",
-          "description": "A list of room aliases for this room.",
-          "items": {
-            "$ref": "string"
-          }
-        },
-        "name": {
-          "type": "string",
-          "description": "The name of the room, as given by the m.room.name state event."
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The room ID for this public room.",
-          "required": true
-        },
-        "topic": {
-          "type": "string",
-          "description": "The topic of this room, as given by the m.room.topic state event."
-        }
-      }
-    },
-    "PublicRoomsPaginationChunk": {
-      "id": "PublicRoomsPaginationChunk",
-      "properties": {
-        "start": {
-          "type": "string",
-          "description": "A token which correlates to the first value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "end": {
-          "type": "string",
-          "description": "A token which correlates to the last value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "chunk": {
-          "type": "array",
-          "description": "A list of public room data.",
-          "required": true,
-          "items": {
-            "$ref": "PublicRoomInfo"
-          }
-        }
-      }
-    },
-    "InitialSyncResponse": {
-      "id": "InitialSyncResponse",
-      "properties": {
-        "end": {
-          "type": "string",
-          "description": "A streaming token which can be used with /events to continue from this snapshot of data.",
-          "required": true
-        },
-        "presence": {
-          "type": "array",
-          "description": "A list of presence events.",
-          "items": {
-            "$ref": "Event"
-          },
-          "required": false
-        },
-        "rooms": {
-          "type": "array",
-          "description": "A list of initial sync room data.",
-          "required": false,
-          "items": {
-            "$ref": "InitialSyncRoomData"
-          }
-        }
-      }
-    },
-    "InitialSyncRoomData": {
-      "id": "InitialSyncRoomData",
-      "properties": {
-        "membership": {
-          "type": "string",
-          "description": "This user's membership state in this room.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The ID of this room.",
-          "required": true
-        },
-        "messages": {
-          "type": "PaginationChunk",
-          "description": "The most recent messages for this room, governed by the limit parameter.",
-          "required": false
-        },
-        "state": {
-          "type": "array",
-          "description": "A list of state events representing the current state of the room.",
-          "required": false,
-          "items": {
-            "$ref": "Event"
-          }
-        }
-      }
-    }
-  }
-}
diff --git a/docs/client-server/swagger_matrix/api-docs-login b/docs/client-server/swagger_matrix/api-docs-login
deleted file mode 100644
index d6f8d84f29..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-login
+++ /dev/null
@@ -1,120 +0,0 @@
-{
-  "apiVersion": "1.0.0", 
-  "apis": [
-    {
-      "operations": [
-        {
-          "method": "GET", 
-          "nickname": "get_login_info", 
-          "notes": "All login stages MUST be mentioned if there is >1 login type.", 
-          "summary": "Get the login mechanism to use when logging in.", 
-          "type": "LoginFlows"
-        }, 
-        {
-          "method": "POST", 
-          "nickname": "submit_login", 
-          "notes": "If this is part of a multi-stage login, there MUST be a 'session' key.", 
-          "parameters": [
-            {
-              "description": "A login submission", 
-              "name": "body", 
-              "paramType": "body", 
-              "required": true, 
-              "type": "LoginSubmission"
-            }
-          ], 
-          "responseMessages": [
-            {
-              "code": 400, 
-              "message": "Bad login type"
-            }, 
-            {
-              "code": 400, 
-              "message": "Missing JSON keys"
-            }
-          ], 
-          "summary": "Submit a login action.", 
-          "type": "LoginResult"
-        }
-      ], 
-      "path": "/login"
-    }
-  ], 
-  "basePath": "http://localhost:8008/_matrix/client/api/v1", 
-  "consumes": [
-    "application/json"
-  ], 
-  "models": {
-    "LoginFlows": {
-      "id": "LoginFlows",
-      "properties": {
-        "flows": {
-          "description": "A list of valid login flows.",
-          "type": "array",
-          "items": {
-            "$ref": "LoginInfo"
-          }
-        }
-      }
-    },
-    "LoginInfo": {
-      "id": "LoginInfo", 
-      "properties": {
-        "stages": {
-          "description": "Multi-stage login only: An array of all the login types required to login.", 
-          "items": {
-            "$ref": "string"
-          }, 
-          "type": "array"
-        }, 
-        "type": {
-          "description": "The login type that must be used when logging in.", 
-          "type": "string"
-        }
-      }
-    }, 
-    "LoginResult": {
-      "id": "LoginResult", 
-      "properties": {
-        "access_token": {
-          "description": "The access token for this user's login if this is the final stage of the login process.", 
-          "type": "string"
-        },
-        "user_id": {
-          "description": "The user's fully-qualified user ID.",
-          "type": "string"
-        }, 
-        "next": {
-          "description": "Multi-stage login only: The next login type to submit.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage login only: The session token to send when submitting the next login type.",
-          "type": "string"
-        }
-      }
-    }, 
-    "LoginSubmission": {
-      "id": "LoginSubmission", 
-      "properties": {
-        "type": {
-          "description": "The type of login being submitted.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage login only: The session token from an earlier login stage.",
-          "type": "string"
-        },
-        "_login_type_defined_keys_": {
-          "description": "Keys as defined by the specified login type, e.g. \"user\", \"password\""
-        }
-      }
-    }
-  }, 
-  "produces": [
-    "application/json"
-  ], 
-  "resourcePath": "/login", 
-  "swaggerVersion": "1.2"
-}
-
diff --git a/docs/client-server/swagger_matrix/api-docs-presence b/docs/client-server/swagger_matrix/api-docs-presence
deleted file mode 100644
index 6b22446024..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-presence
+++ /dev/null
@@ -1,164 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/presence",
-  "produces": [
-    "application/json"
-  ],
-  "consumes": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/presence/{userId}/status",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Update this user's presence state.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "update_presence",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new presence state",
-              "required": true,
-              "type": "PresenceUpdate",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose presence to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get this user's presence state.",
-          "notes": "Get this user's presence state.",
-          "type": "PresenceUpdate",
-          "nickname": "get_presence",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/presence/list/{userId}",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Retrieve a list of presences for all of this user's friends.",
-          "notes": "",
-          "type": "array",
-          "items": {
-            "$ref": "Presence"
-          },
-          "nickname": "get_presence_list",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence list to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "POST",
-          "summary": "Add or remove users from this presence list.",
-          "notes": "Add or remove users from this presence list.",
-          "type": "void",
-          "nickname": "modify_presence_list",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose presence list is being modified.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The modifications to make to this presence list.",
-              "required": true,
-              "type": "PresenceListModifications",
-              "paramType": "body"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "PresenceUpdate": {
-      "id": "PresenceUpdate",
-      "properties": {
-        "presence": {
-          "type": "string",
-          "description": "Enum: The presence state.",
-          "enum": [
-            "offline",
-            "unavailable",
-            "online",
-            "free_for_chat"
-          ]
-        },
-        "status_msg": {
-          "type": "string",
-          "description": "The user-defined message associated with this presence state."
-        }
-      },
-      "subTypes": [
-        "Presence"
-      ]
-    },
-    "Presence": {
-      "id": "Presence",
-      "properties": {
-        "last_active_ago": {
-          "type": "integer",
-          "format": "int64",
-          "description": "The last time this user performed an action on their home server."
-        },
-        "user_id": {
-          "type": "string",
-          "description": "The fully qualified user ID"
-        }
-      }
-    },
-    "PresenceListModifications": {
-      "id": "PresenceListModifications",
-      "properties": {
-        "invite": {
-          "type": "array",
-          "description": "A list of user IDs to add to the list.",
-          "items": {
-            "type": "string",
-            "description": "A fully qualified user ID."
-          }
-        },
-        "drop": {
-          "type": "array",
-          "description": "A list of user IDs to remove from the list.",
-          "items": {
-            "type": "string",
-            "description": "A fully qualified user ID."
-          }
-        }
-      }
-    }
-  }
-}
diff --git a/docs/client-server/swagger_matrix/api-docs-profile b/docs/client-server/swagger_matrix/api-docs-profile
deleted file mode 100644
index d2fccaa67d..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-profile
+++ /dev/null
@@ -1,122 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1",
-  "resourcePath": "/profile",
-  "produces": [
-    "application/json"
-  ],
-  "consumes": [
-    "application/json"
-  ],
-  "apis": [
-    {
-      "path": "/profile/{userId}/displayname",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set a display name.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "set_display_name",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new display name for this user.",
-              "required": true,
-              "type": "DisplayName",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose display name to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get a display name.",
-          "notes": "This can be done by anyone.",
-          "type": "DisplayName",
-          "nickname": "get_display_name",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose display name to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/profile/{userId}/avatar_url",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set an avatar URL.",
-          "notes": "This can only be done by the logged in user.",
-          "type": "void",
-          "nickname": "set_avatar_url",
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new avatar url for this user.",
-              "required": true,
-              "type": "AvatarUrl",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose avatar url to set.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get an avatar url.",
-          "notes": "This can be done by anyone.",
-          "type": "AvatarUrl",
-          "nickname": "get_avatar_url",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose avatar url to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "DisplayName": {
-      "id": "DisplayName",
-      "properties": {
-        "displayname": {
-          "type": "string",
-          "description": "The textual display name"
-        }
-      }
-    },
-    "AvatarUrl": {
-      "id": "AvatarUrl",
-      "properties": {
-        "avatar_url": {
-          "type": "string",
-          "description": "A url to an image representing an avatar."
-        }
-      }
-    }
-  }
-}
diff --git a/docs/client-server/swagger_matrix/api-docs-registration b/docs/client-server/swagger_matrix/api-docs-registration
deleted file mode 100644
index 11c170c3ec..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-registration
+++ /dev/null
@@ -1,120 +0,0 @@
-{
-  "apiVersion": "1.0.0", 
-  "apis": [
-    {
-      "operations": [
-        {
-          "method": "GET", 
-          "nickname": "get_registration_info", 
-          "notes": "All login stages MUST be mentioned if there is >1 login type.", 
-          "summary": "Get the login mechanism to use when registering.", 
-          "type": "RegistrationFlows"
-        }, 
-        {
-          "method": "POST", 
-          "nickname": "submit_registration", 
-          "notes": "If this is part of a multi-stage registration, there MUST be a 'session' key.", 
-          "parameters": [
-            {
-              "description": "A registration submission", 
-              "name": "body", 
-              "paramType": "body", 
-              "required": true, 
-              "type": "RegistrationSubmission"
-            }
-          ], 
-          "responseMessages": [
-            {
-              "code": 400, 
-              "message": "Bad login type"
-            }, 
-            {
-              "code": 400, 
-              "message": "Missing JSON keys"
-            }
-          ], 
-          "summary": "Submit a registration action.", 
-          "type": "RegistrationResult"
-        }
-      ], 
-      "path": "/register"
-    }
-  ], 
-  "basePath": "http://localhost:8008/_matrix/client/api/v1", 
-  "consumes": [
-    "application/json"
-  ], 
-  "models": {
-    "RegistrationFlows": {
-      "id": "RegistrationFlows",
-      "properties": {
-        "flows": {
-          "description": "A list of valid registration flows.",
-          "type": "array",
-          "items": {
-            "$ref": "RegistrationInfo"
-          }
-        }
-      }
-    },
-    "RegistrationInfo": {
-      "id": "RegistrationInfo", 
-      "properties": {
-        "stages": {
-          "description": "Multi-stage registration only: An array of all the login types required to registration.", 
-          "items": {
-            "$ref": "string"
-          }, 
-          "type": "array"
-        }, 
-        "type": {
-          "description": "The first login type that must be used when logging in.", 
-          "type": "string"
-        }
-      }
-    }, 
-    "RegistrationResult": {
-      "id": "RegistrationResult", 
-      "properties": {
-        "access_token": {
-          "description": "The access token for this user's registration if this is the final stage of the registration process.", 
-          "type": "string"
-        },
-        "user_id": {
-          "description": "The user's fully-qualified user ID.",
-          "type": "string"
-        }, 
-        "next": {
-          "description": "Multi-stage registration only: The next registration type to submit.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage registration only: The session token to send when submitting the next registration type.",
-          "type": "string"
-        }
-      }
-    }, 
-    "RegistrationSubmission": {
-      "id": "RegistrationSubmission", 
-      "properties": {
-        "type": {
-          "description": "The type of registration being submitted.", 
-          "type": "string"
-        },
-        "session": {
-          "description": "Multi-stage registration only: The session token from an earlier registration stage.",
-          "type": "string"
-        },
-        "_registration_type_defined_keys_": {
-          "description": "Keys as defined by the specified registration type, e.g. \"user\", \"password\""
-        }
-      }
-    }
-  }, 
-  "produces": [
-    "application/json"
-  ], 
-  "resourcePath": "/register", 
-  "swaggerVersion": "1.2"
-}
-
diff --git a/docs/client-server/swagger_matrix/api-docs-rooms b/docs/client-server/swagger_matrix/api-docs-rooms
deleted file mode 100644
index b941e58139..0000000000
--- a/docs/client-server/swagger_matrix/api-docs-rooms
+++ /dev/null
@@ -1,977 +0,0 @@
-{
-  "apiVersion": "1.0.0",
-  "swaggerVersion": "1.2",
-  "basePath": "http://localhost:8008/_matrix/client/api/v1", 
-  "resourcePath": "/rooms",
-  "produces": [
-    "application/json"
-  ],
-  "consumes": [
-    "application/json"
-  ],
-  "authorizations": {
-    "token": []
-  },
-  "apis": [
-    {
-      "path": "/rooms/{roomId}/send/{eventType}",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Send a generic non-state event to this room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "EventId",
-          "nickname": "send_non_state_event",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The event contents",
-              "required": true,
-              "type": "EventContent",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to send the message in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "eventType",
-              "description": "The type of event to send.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/state/{eventType}/{stateKey}",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Send a generic state event to this room.",
-          "notes": "The state key can be omitted, such that you can PUT to /rooms/{roomId}/state/{eventType}. The state key defaults to a 0 length string in this case.",
-          "type": "void",
-          "nickname": "send_state_event",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The event contents",
-              "required": true,
-              "type": "EventContent",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to send the message in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "eventType",
-              "description": "The type of event to send.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "stateKey",
-              "description": "An identifier used to specify clobbering semantics. State events with the same (roomId, eventType, stateKey) will be replaced.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/send/m.room.message",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Send a message in this room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "EventId",
-          "nickname": "send_message",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The message contents",
-              "required": true,
-              "type": "Message",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to send the message in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/state/m.room.topic",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set the topic for this room.",
-          "notes": "Set the topic for this room.",
-          "type": "void",
-          "nickname": "set_topic",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The topic contents",
-              "required": true,
-              "type": "Topic",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to set the topic in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get the topic for this room.",
-          "notes": "Get the topic for this room.",
-          "type": "Topic",
-          "nickname": "get_topic",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get topic in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 404,
-              "message": "Topic not found."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/state/m.room.name",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Set the name of this room.",
-          "notes": "Set the name of this room.",
-          "type": "void",
-          "nickname": "set_room_name",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The name contents",
-              "required": true,
-              "type": "RoomName",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to set the name of.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get the room's name.",
-          "notes": "",
-          "type": "RoomName",
-          "nickname": "get_room_name",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get the name of.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 404,
-              "message": "Name not found."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/send/m.room.message.feedback",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Send feedback to a message.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "EventId",
-          "nickname": "send_feedback",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The feedback contents",
-              "required": true,
-              "type": "Feedback",
-              "paramType": "body"
-            },
-            {
-              "name": "roomId",
-              "description": "The room to send the feedback in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Bad feedback type."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/invite",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Invite a user to this room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "void",
-          "nickname": "invite",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room which has this user.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The user to invite.",
-              "required": true,
-              "type": "InviteRequest",
-              "paramType": "body"
-            }
-          ]
-        }  
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/join",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Join this room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "void",
-          "nickname": "join_room",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to join.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "required": true,
-              "type": "JoinRequest",
-              "paramType": "body"
-            }
-          ]
-        }  
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/leave",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Leave this room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}.",
-          "type": "void",
-          "nickname": "leave",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to leave.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "required": true,
-              "type": "LeaveRequest",
-              "paramType": "body"
-            }
-          ]
-        }  
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/ban",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Ban a user in the room.",
-          "notes": "This operation can also be done as a PUT by suffixing /{txnId}. The caller must have the required power level to do this operation.",
-          "type": "void",
-          "nickname": "ban",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room which has the user to ban.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "body",
-              "description": "The user to ban.",
-              "required": true,
-              "type": "BanRequest",
-              "paramType": "body"
-            }
-          ]
-        }  
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/state/m.room.member/{userId}",
-      "operations": [
-        {
-          "method": "PUT",
-          "summary": "Change the membership state for a user in a room.",
-          "notes": "Change the membership state for a user in a room.",
-          "type": "void",
-          "nickname": "set_membership",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The new membership state",
-              "required": true,
-              "type": "Member",
-              "paramType": "body"
-            },
-            {
-              "name": "userId",
-              "description": "The user whose membership is being changed.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "roomId",
-              "description": "The room which has this user.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "No membership key."
-            },
-            {
-              "code": 400,
-              "message": "Bad membership value."
-            },
-            {
-              "code": 403,
-              "message": "When inviting: You are not in the room."
-            },
-            {
-              "code": 403,
-              "message": "When inviting: <target> is already in the room."
-            },
-            {
-              "code": 403,
-              "message": "When joining: Cannot force another user to join."
-            },
-            {
-              "code": 403,
-              "message": "When joining: You are not invited to this room."
-            }
-          ]
-        },
-        {
-          "method": "GET",
-          "summary": "Get the membership state of a user in a room.",
-          "notes": "Get the membership state of a user in a room.",
-          "type": "Member",
-          "nickname": "get_membership",
-          "parameters": [
-            {
-              "name": "userId",
-              "description": "The user whose membership state you want to get.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "roomId",
-              "description": "The room which has this user.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 404,
-              "message": "Member not found."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/join/{roomAliasOrId}",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Join a room via a room alias or room ID.",
-          "notes": "Join a room via a room alias or room ID.",
-          "type": "JoinRoomInfo",
-          "nickname": "join",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "roomAliasOrId",
-              "description": "The room alias or room ID to join.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Bad room alias."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/createRoom",
-      "operations": [
-        {
-          "method": "POST",
-          "summary": "Create a room.",
-          "notes": "Create a room.",
-          "type": "RoomInfo",
-          "nickname": "create_room",
-          "consumes": [
-            "application/json"
-          ],
-          "parameters": [
-            {
-              "name": "body",
-              "description": "The desired configuration for the room. This operation can also be done as a PUT by suffixing /{txnId}.",
-              "required": true,
-              "type": "RoomConfig",
-              "paramType": "body"
-            }
-          ],
-          "responseMessages": [
-            {
-              "code": 400,
-              "message": "Body must be JSON."
-            },
-            {
-              "code": 400,
-              "message": "Room alias already taken."
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/messages",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a list of messages for this room.",
-          "notes": "Get a list of messages for this room.",
-          "type": "MessagePaginationChunk",
-          "nickname": "get_messages",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get messages in.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "from",
-              "description": "The token to start getting results from.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "to",
-              "description": "The token to stop getting results at.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "limit",
-              "description": "The maximum number of messages to return.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/members",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a list of members for this room.",
-          "notes": "Get a list of members for this room.",
-          "type": "MemberPaginationChunk",
-          "nickname": "get_members",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get a list of members from.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            },
-            {
-              "name": "from",
-              "description": "The token to start getting results from.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "to",
-              "description": "The token to stop getting results at.",
-              "required": false,
-              "type": "string",
-              "paramType": "query"
-            },
-            {
-              "name": "limit",
-              "description": "The maximum number of members to return.",
-              "required": false,
-              "type": "integer",
-              "paramType": "query"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/state",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get a list of all the current state events for this room.",
-          "notes": "This is equivalent to the events returned under the 'state' key for this room in /initialSync.",
-          "type": "array",
-          "items": {
-            "$ref": "Event"
-          },
-          "nickname": "get_state_events",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get a list of current state events from.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    },
-    {
-      "path": "/rooms/{roomId}/initialSync",
-      "operations": [
-        {
-          "method": "GET",
-          "summary": "Get all the current information for this room, including messages and state events.",
-          "notes": "NOT YET IMPLEMENTED.",
-          "type": "InitialSyncRoomData",
-          "nickname": "get_room_sync_data",
-          "parameters": [
-            {
-              "name": "roomId",
-              "description": "The room to get information for.",
-              "required": true,
-              "type": "string",
-              "paramType": "path"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "models": {
-    "Topic": {
-      "id": "Topic",
-      "properties": {
-        "topic": {
-          "type": "string",
-          "description": "The topic text"
-        }
-      }
-    },
-    "RoomName": {
-      "id": "RoomName",
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "The human-readable name for the room. Can contain spaces."
-        }
-      }
-    },
-    "Message": {
-      "id": "Message",
-      "properties": {
-        "msgtype": {
-          "type": "string",
-          "description": "The type of message being sent, e.g. \"m.text\"",
-          "required": true
-        },
-        "_msgtype_defined_keys_": {
-          "description": "Additional keys as defined by the msgtype, e.g. \"body\""
-        }
-      }
-    },
-    "Feedback": {
-      "id": "Feedback",
-      "properties": {
-        "target_event_id": {
-          "type": "string",
-          "description": "The event ID being acknowledged.",
-          "required": true
-        },
-        "type": {
-          "type": "string",
-          "description": "The type of feedback. Either 'delivered' or 'read'.",
-          "required": true
-        }
-      }
-    },
-    "Member": {
-      "id": "Member",
-      "properties": {
-        "membership": {
-          "type": "string",
-          "description": "Enum: The membership state of this member.",
-          "enum": [
-            "invite",
-            "join",
-            "leave",
-            "ban"
-          ]
-        }
-      }
-    },
-    "RoomInfo": {
-      "id": "RoomInfo",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The allocated room ID.",
-          "required": true
-        },
-        "room_alias": {
-          "type": "string",
-          "description": "The alias for the room.",
-          "required": false
-        }
-      }
-    },
-    "JoinRoomInfo": {
-      "id": "JoinRoomInfo",
-      "properties": {
-        "room_id": {
-          "type": "string",
-          "description": "The room ID joined, if joined via a room alias only.",
-          "required": true
-        }
-      }
-    },
-    "RoomConfig": {
-      "id": "RoomConfig",
-      "properties": {
-        "visibility": {
-          "type": "string",
-          "description": "Enum: The room visibility.",
-          "required": false,
-          "enum": [
-            "public",
-            "private"
-          ]
-        },
-        "room_alias_name": {
-          "type": "string",
-          "description": "The alias to give the new room.",
-          "required": false
-        },
-        "name": {
-          "type": "string",
-          "description": "Sets the name of the room. Send a m.room.name event after creating the room with the 'name' key specified.",
-          "required": false
-        },
-        "topic": {
-          "type": "string",
-          "description": "Sets the topic for the room. Send a m.room.topic event after creating the room with the 'topic' key specified.",
-          "required": false
-        }
-      }
-    },
-    "PaginationRequest": {
-      "id": "PaginationRequest",
-      "properties": {
-        "from": {
-          "type": "string",
-          "description": "The token to start getting results from."
-        },
-        "to": {
-          "type": "string",
-          "description": "The token to stop getting results at."
-        },
-        "limit": {
-          "type": "integer",
-          "description": "The maximum number of entries to return."
-        }
-      }
-    },
-    "PaginationChunk": {
-      "id": "PaginationChunk",
-      "properties": {
-        "start": {
-          "type": "string",
-          "description": "A token which correlates to the first value in \"chunk\" for paginating.",
-          "required": true
-        },
-        "end": {
-          "type": "string",
-          "description": "A token which correlates to the last value in \"chunk\" for paginating.",
-          "required": true
-        }
-      },
-      "subTypes": [
-        "MessagePaginationChunk"
-      ]
-    },
-    "MessagePaginationChunk": {
-      "id": "MessagePaginationChunk",
-      "properties": {
-        "chunk": {
-          "type": "array",
-          "description": "A list of message events.",
-          "items": {
-            "$ref": "MessageEvent"
-          },
-          "required": true
-        }
-      }
-    },
-    "MemberPaginationChunk": {
-      "id": "MemberPaginationChunk",
-      "properties": {
-        "chunk": {
-          "type": "array",
-          "description": "A list of member events.",
-          "items": {
-            "$ref": "MemberEvent"
-          },
-          "required": true
-        }
-      }
-    },
-    "Event": {
-      "id": "Event",
-      "properties": {
-        "event_id": {
-          "type": "string",
-          "description": "An ID which uniquely identifies this event. This is automatically set by the server.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The room in which this event occurred. This is automatically set by the server.",
-          "required": true
-        },
-        "type": {
-          "type": "string",
-          "description": "The event type.",
-          "required": true
-        }
-      },
-      "subTypes": [
-        "MessageEvent"
-      ]
-    },
-    "EventId": {
-      "id": "EventId",
-      "properties": {
-        "event_id": {
-          "type": "string",
-          "description": "The allocated event ID for this event.",
-          "required": true
-        }
-      }
-    },
-    "EventContent": {
-      "id": "EventContent",
-      "properties": {
-        "__event_content_keys__": {
-          "type": "string",
-          "description": "Event-specific content keys and values.",
-          "required": false
-        }
-      }
-    },
-    "MessageEvent": {
-      "id": "MessageEvent",
-      "properties": {
-        "content": {
-          "type": "Message"
-        }
-      }
-    },
-    "MemberEvent": {
-      "id": "MemberEvent",
-      "properties": {
-        "content": {
-          "type": "Member"
-        }
-      }
-    },
-    "InviteRequest": {
-      "id": "InviteRequest",
-      "properties": {
-        "user_id": {
-          "type": "string",
-          "description": "The fully-qualified user ID."
-        }
-      }
-    },
-    "JoinRequest": {
-      "id": "JoinRequest",
-      "properties": {}
-    },
-    "LeaveRequest": {
-      "id": "LeaveRequest",
-      "properties": {}
-    },
-    "BanRequest": {
-      "id": "BanRequest",
-      "properties": {
-        "user_id": {
-          "type": "string",
-          "description": "The fully-qualified user ID."
-        },
-        "reason": {
-          "type": "string",
-          "description": "The reason for the ban."
-        }
-      }
-    },
-    "InitialSyncRoomData": {
-      "id": "InitialSyncRoomData",
-      "properties": {
-        "membership": {
-          "type": "string",
-          "description": "This user's membership state in this room.",
-          "required": true
-        },
-        "room_id": {
-          "type": "string",
-          "description": "The ID of this room.",
-          "required": true
-        },
-        "messages": {
-          "type": "MessagePaginationChunk",
-          "description": "The most recent messages for this room, governed by the limit parameter.",
-          "required": false
-        },
-        "state": {
-          "type": "array",
-          "description": "A list of state events representing the current state of the room.",
-          "required": false,
-          "items": {
-            "$ref": "Event"
-          }
-        }
-      }
-    }
-  }
-}
diff --git a/docs/freenode.txt b/docs/freenode.txt
deleted file mode 100644
index 84fdf6d523..0000000000
--- a/docs/freenode.txt
+++ /dev/null
@@ -1 +0,0 @@
-NCjcRSEG
diff --git a/docs/human-id-rules.rst b/docs/human-id-rules.rst
deleted file mode 100644
index 3a1ff39892..0000000000
--- a/docs/human-id-rules.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-This document outlines the format for human-readable IDs within matrix.
-
-Overview
---------
-UTF-8 is quickly becoming the standard character encoding set on the web. As
-such, Matrix requires that all strings MUST be encoded as UTF-8. However,
-using Unicode as the character set for human-readable IDs is troublesome. There
-are many different characters which appear identical to each other, but would
-identify different users. In addition, there are non-printable characters which
-cannot be rendered by the end-user. This opens up a security vulnerability with
-phishing/spoofing of IDs, commonly known as a homograph attack.
-
-Web browers encountered this problem when International Domain Names were
-introduced. A variety of checks were put in place in order to protect users. If
-an address failed the check, the raw punycode would be displayed to disambiguate
-the address. Similar checks are performed by home servers in Matrix. However, 
-Matrix does not use punycode representations, and so does not show raw punycode 
-on a failed check. Instead, home servers must outright reject these misleading 
-IDs.
-
-Types of human-readable IDs
----------------------------
-There are two main human-readable IDs in question:
-
-- Room aliases
-- User IDs
- 
-Room aliases look like ``#localpart:domain``. These aliases point to opaque
-non human-readable room IDs. These pointers can change, so there is already an
-issue present with the same ID pointing to a different destination at a later
-date.
-
-User IDs look like ``@localpart:domain``. These represent actual end-users, and
-unlike room aliases, there is no layer of indirection. This presents a much
-greater concern with homograph attacks. 
-
-Checks
-------
-- Similar to web browsers.
-- blacklisted chars (e.g. non-printable characters)
-- mix of language sets from 'preferred' language not allowed. 
-- Language sets from CLDR dataset.
-- Treated in segments (localpart, domain)
-- Additional restrictions for ease of processing IDs.
-   - Room alias localparts MUST NOT have ``#`` or ``:``.
-   - User ID localparts MUST NOT have ``@`` or ``:``.
-
-Rejecting
----------
-- Home servers MUST reject room aliases which do not pass the check, both on 
-  GETs and PUTs.
-- Home servers MUST reject user ID localparts which do not pass the check, both
-  on creation and on events.
-- Any home server whose domain does not pass this check, MUST use their punycode
-  domain name instead of the IDN, to prevent other home servers rejecting you.
-- Error code is ``M_FAILED_HUMAN_ID_CHECK``. (generic enough for both failing 
-  due to homograph attacks, and failing due to including ``:`` s, etc)
-- Error message MAY go into further information about which characters were
-  rejected and why.
-- Error message SHOULD contain a ``failed_keys`` key which contains an array
-  of strings which represent the keys which failed the check e.g::
-  
-    failed_keys: [ user_id, room_alias ]
-  
-Other considerations
---------------------
-- Basic security: Informational key on the event attached by HS to say "unsafe 
-  ID". Problem: clients can just ignore it, and since it will appear only very
-  rarely, easy to forget when implementing clients.
-- Moderate security: Requires client handshake. Forces clients to implement
-  a check, else they cannot communicate with the misleading ID. However, this is
-  extra overhead in both client implementations and round-trips.
-- High security: Outright rejection of the ID at the point of creation / 
-  receiving event. Point of creation rejection is preferable to avoid the ID
-  entering the system in the first place. However, malicious HSes can just allow
-  the ID. Hence, other home servers must reject them if they see them in events.
-  Client never sees the problem ID, provided the HS is correctly implemented.
-- High security decided; client doesn't need to worry about it, no additional
-  protocol complexity aside from rejection of an event.
\ No newline at end of file
diff --git a/docs/implementation-notes/documentation_style.rst b/docs/implementation-notes/documentation_style.rst
deleted file mode 100644
index c365d09dff..0000000000
--- a/docs/implementation-notes/documentation_style.rst
+++ /dev/null
@@ -1,43 +0,0 @@
-===================
-Documentation Style
-===================
-
-A brief single sentence to describe what this file contains; in this case a
-description of the style to write documentation in.
-
-
-Sections
-========
-
-Each section should be separated from the others by two blank lines. Headings
-should be underlined using a row of equals signs (===). Paragraphs should be
-separated by a single blank line, and wrap to no further than 80 columns.
-
-[[TODO(username): if you want to leave some unanswered questions, notes for
-further consideration, or other kinds of comment, use a TODO section. Make sure
-to notate it with your name so we know who to ask about it!]]
-
-Subsections
------------
-
-If required, subsections can use a row of dashes to underline their header. A
-single blank line between subsections of a single section.
-
-
-Bullet Lists
-============
-
- * Bullet lists can use asterisks with a single space either side.
- 
- * Another blank line between list elements.
-
-
-Definition Lists
-================
-
-Terms:
-  Start in the first column, ending with a colon
-
-Definitions:
-  Take a two space indent, following immediately from the term without a blank
-  line before it, but having a blank line afterwards.
diff --git a/docs/server-server/signing.rst b/docs/server-server/signing.rst
new file mode 100644
index 0000000000..dae10f121b
--- /dev/null
+++ b/docs/server-server/signing.rst
@@ -0,0 +1,151 @@
+Signing JSON
+============
+
+JSON is signed by encoding the JSON object without ``signatures`` or ``meta``
+keys using a canonical encoding. The JSON bytes are then signed using the
+signature algorithm and the signature encoded using base64 with the padding
+stripped. The resulting base64 signature is added to an object under the
+*signing key identifier* which is added to the ``signatures`` object under the
+name of the server signing it which is added back to the original JSON object
+along with the ``meta`` object.
+
+The *signing key identifier* is the concatenation of the *signing algorithm*
+and a *key version*. The *signing algorithm* identifies the algorithm used to
+sign the JSON. The currently support value for *signing algorithm* is
+``ed25519`` as implemented by NACL (http://nacl.cr.yp.to/). The *key version*
+is used to distinguish between different signing keys used by the same entity.
+
+The ``meta`` object and the ``signatures`` object are not covered by the
+signature. Therefore intermediate servers can add metadata such as time stamps
+and additional signatures.
+
+
+::
+
+  {
+     "name": "example.org",
+     "signing_keys": {
+       "ed25519:1": "XSl0kuyvrXNj6A+7/tkrB9sxSbRi08Of5uRhxOqZtEQ"
+     },
+     "meta": {
+        "retrieved_ts_ms": 922834800000
+     },
+     "signatures": {
+        "example.org": {
+           "ed25519:1": "s76RUgajp8w172am0zQb/iPTHsRnb4SkrzGoeCOSFfcBY2V/1c8QfrmdXHpvnc2jK5BD1WiJIxiMW95fMjK7Bw"
+        }
+     }
+  }
+
+::
+
+  def sign_json(json_object, signing_key, signing_name):
+      signatures = json_object.pop("signatures", {})
+      meta = json_object.pop("meta", None)
+
+      signed = signing_key.sign(encode_canonical_json(json_object))
+      signature_base64 = encode_base64(signed.signature)
+
+      key_id = "%s:%s" % (signing_key.alg, signing_key.version)
+      signatures.setdefault(sigature_name, {})[key_id] = signature_base64
+
+      json_object["signatures"] = signatures
+      if meta is not None:
+          json_object["meta"] = meta
+
+      return json_object
+
+Checking for a Signature
+------------------------
+
+To check if an entity has signed a JSON object a server does the following
+
+1. Checks if the ``signatures`` object contains an entry with the name of the
+   entity. If the entry is missing then the check fails.
+2. Removes any *signing key identifiers* from the entry with algorithms it
+   doesn't understand. If there are no *signing key identifiers* left then the
+   check fails.
+3. Looks up *verification keys* for the remaining *signing key identifiers*
+   either from a local cache or by consulting a trusted key server. If it
+   cannot find a *verification key* then the check fails.
+4. Decodes the base64 encoded signature bytes. If base64 decoding fails then
+   the check fails.
+5. Checks the signature bytes using the *verification key*. If this fails then
+   the check fails. Otherwise the check succeeds.
+
+Canonical JSON
+--------------
+
+The canonical JSON encoding for a value is the shortest UTF-8 JSON encoding
+with dictionary keys lexicographically sorted by unicode codepoint. Numbers in
+the JSON value must be integers in the range [-(2**53)+1, (2**53)-1].
+
+::
+
+ import json
+
+ def canonical_json(value):
+     return json.dumps(
+         value,
+         ensure_ascii=False,
+         separators=(',',':'),
+         sort_keys=True,
+     ).encode("UTF-8")
+
+Grammar
++++++++
+
+Adapted from the grammar in http://tools.ietf.org/html/rfc7159 removing
+insignificant whitespace, fractions, exponents and redundant character escapes
+
+::
+
+ value     = false / null / true / object / array / number / string
+ false     = %x66.61.6c.73.65
+ null      = %x6e.75.6c.6c
+ true      = %x74.72.75.65
+ object    = %x7B [ member *( %x2C member ) ] %7D
+ member    = string %x3A value
+ array     = %x5B [ value *( %x2C value ) ] %5B
+ number    = [ %x2D ] int
+ int       = %x30 / ( %x31-39 *digit )
+ digit     = %x30-39
+ string    = %x22 *char %x22
+ char      = unescaped / %x5C escaped
+ unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
+ escaped   = %x22 ; "    quotation mark  U+0022
+           / %x5C ; \    reverse solidus U+005C
+           / %x62 ; b    backspace       U+0008
+           / %x66 ; f    form feed       U+000C
+           / %x6E ; n    line feed       U+000A
+           / %x72 ; r    carriage return U+000D
+           / %x74 ; t    tab             U+0009
+           / %x75.30.30.30 (%x30-37 / %x62 / %x65-66) ; u000X
+           / %x75.30.30.31 (%x30-39 / %x61-66)        ; u001X
+
+Signing Events
+==============
+
+Signing events is a more complicated process since servers can choose to redact
+non-essential event contents. Before signing the event it is encoded as
+Canonical JSON and hashed using SHA-256. The resulting hash is then stored
+in the event JSON in a ``hash`` object under a ``sha256`` key. Then all
+non-essential keys are stripped from the event object, and the resulting object
+which included the ``hash`` key is signed using the JSON signing algorithm.
+
+Servers can then transmit the entire event or the event with the non-essential
+keys removed. Receiving servers can then check the entire event if it is
+present by computing the SHA-256 of the event excluding the ``hash`` object, or
+by using the ``hash`` object included in the event if keys have been redacted.
+
+New hash functions can be introduced by adding additional keys to the ``hash``
+object. Since the ``hash`` object cannot be redacted a server shouldn't allow
+too many hashes to be listed, otherwise a server might embed illict data within
+the ``hash`` object. For similar reasons a server shouldn't allow hash values
+that are too long.
+
+[[TODO(markjh): We might want to specify a maximum number of keys for the
+``hash`` and we might want to specify the maximum output size of a hash]]
+
+[[TODO(markjh) We might want to allow the server to omit the output of well
+known hash functions like SHA-256 when none of the keys have been redacted]]
diff --git a/docs/specification.rst b/docs/specification.rst
deleted file mode 100644
index 370e238e00..0000000000
--- a/docs/specification.rst
+++ /dev/null
@@ -1,2306 +0,0 @@
-Matrix Specification
-====================
-
-WARNING
-=======
-
-.. WARNING::
-  The Matrix specification is still very much evolving: the API is not yet frozen
-  and this document is in places incomplete, stale, and may contain security
-  issues. Needless to say, we have made every effort to highlight the problem
-  areas that we're aware of.
-
-  We're publishing it at this point because it's complete enough to be more than
-  useful and provide a canonical reference to how Matrix is evolving. Our end
-  goal is to mirror WHATWG's `Living Standard <http://wiki.whatwg.org/wiki/FAQ#What_does_.22Living_Standard.22_mean.3F>`_   
-  approach except right now Matrix is more in the process of being born than actually being
-  living!
-
-.. contents:: Table of Contents
-.. sectnum::
-
-Introduction
-============
-
-Matrix is a new set of open APIs for open-federated Instant Messaging and VoIP
-functionality, designed to create and support a new global real-time
-communication ecosystem on the internet. This specification is the ongoing
-result of standardising the APIs used by the various components of the Matrix
-ecosystem to communicate with one another.
-
-The principles that Matrix attempts to follow are:
-
-- Pragmatic Web-friendly APIs (i.e. JSON over REST)
-- Keep It Simple & Stupid
-
-  + provide a simple architecture with minimal third-party dependencies.
-
-- Fully open:
-
-  + Fully open federation - anyone should be able to participate in the global
-    Matrix network
-  + Fully open standard - publicly documented standard with no IP or patent
-    licensing encumbrances
-  + Fully open source reference implementation - liberally-licensed example
-    implementations with no IP or patent licensing encumbrances
-
-- Empowering the end-user
-
-  + The user should be able to choose the server and clients they use
-  + The user should be control how private their communication is
-  + The user should know precisely where their data is stored
-
-- Fully decentralised - no single points of control over conversations or the
-  network as a whole
-- Learning from history to avoid repeating it
-
-  + Trying to take the best aspects of XMPP, SIP, IRC, SMTP, IMAP and NNTP
-    whilst trying to avoid their failings
-
-The functionality that Matrix provides includes:
-
-- Creation and management of fully distributed chat rooms with no
-  single points of control or failure
-- Eventually-consistent cryptographically secure synchronisation of room
-  state across a global open network of federated servers and services
-- Sending and receiving extensible messages in a room with (optional)
-  end-to-end encryption
-- Extensible user management (inviting, joining, leaving, kicking, banning)
-  mediated by a power-level based user privilege system.
-- Extensible room state management (room naming, aliasing, topics, bans)
-- Extensible user profile management (avatars, displaynames, etc)
-- Managing user accounts (registration, login, logout)
-- Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
-  Facebook accounts to authenticate, identify and discover users on Matrix.
-- Trusted federation of Identity servers for:
-
-  + Publishing user public keys for PKI
-  + Mapping of 3PIDs to Matrix IDs
-
-The end goal of Matrix is to be a ubiquitous messaging layer for synchronising
-arbitrary data between sets of people, devices and services - be that for instant
-messages, VoIP call setups, or any other objects that need to be reliably and
-persistently pushed from A to B in an interoperable and federated manner.
-
-
-Architecture
-============
-
-Clients transmit data to other clients through home servers (HSes). Clients do not communicate with each
-other directly.
-
-::
-
-                         How data flows between clients
-                         ==============================
-
-       { Matrix client A }                             { Matrix client B }
-           ^          |                                    ^          |
-           |  events  |                                    |  events  |
-           |          V                                    |          V
-       +------------------+                            +------------------+
-       |                  |---------( HTTP )---------->|                  |
-       |   Home Server    |                            |   Home Server    |
-       |                  |<--------( HTTP )-----------|                  |
-       +------------------+        Federation          +------------------+
-
-A "Client" typically represents a human using a web application or mobile app. Clients use the
-"Client-to-Server" (C-S) API to communicate with their home server, which stores their profile data and
-their record of the conversations in which they participate. Each client is associated with a user account
-(and may optionally support multiple user accounts). A user account is represented by a unique "User ID". This
-ID is namespaced to the home server which allocated the account and looks like::
-
-  @localpart:domain
-
-The ``localpart`` of a user ID may be a user name, or an opaque ID identifying this user. They are
-case-insensitive.
-
-.. TODO
-    - Need to specify precise grammar for Matrix IDs
-
-A "Home Server" is a server which provides C-S APIs and has the ability to federate with other HSes.
-It is typically responsible for multiple clients. "Federation" is the term used to describe the
-sharing of data between two or more home servers.
-
-Data in Matrix is encapsulated in an "event". An event is an action within the system. Typically each
-action (e.g. sending a message) correlates with exactly one event. Each event has a ``type`` which is used
-to differentiate different kinds of data. ``type`` values MUST be uniquely globally namespaced following
-Java's `package naming conventions <http://docs.oracle.com/javase/specs/jls/se5.0/html/packages.html#7.7>`,
-e.g. ``com.example.myapp.event``. The special top-level namespace ``m.`` is reserved for events defined
-in the Matrix specification. Events are usually sent in the context of a "Room".
-
-Room structure
---------------
-
-A room is a conceptual place where users can send and receive events. Rooms 
-can be created, joined and left. Events are sent to a room, and all 
-participants in that room with sufficient access will receive the event. Rooms are uniquely 
-identified internally via a "Room ID", which look like::
-
-  !opaque_id:domain
-
-There is exactly one room ID for each room. Whilst the room ID does contain a
-domain, it is simply for globally namespacing room IDs. The room does NOT reside on the
-domain specified. Room IDs are not meant to be human readable. They ARE
-case-sensitive.
-
-The following diagram shows an ``m.room.message`` event being sent in the room 
-``!qporfwt:matrix.org``::
-
-       { @alice:matrix.org }                             { @bob:domain.com }
-               |                                                 ^
-               |                                                 |
-      Room ID: !qporfwt:matrix.org                 Room ID: !qporfwt:matrix.org
-      Event type: m.room.message                   Event type: m.room.message
-      Content: { JSON object }                     Content: { JSON object }
-               |                                                 |
-               V                                                 |
-       +------------------+                          +------------------+
-       |   Home Server    |                          |   Home Server    |
-       |   matrix.org     |<-------Federation------->|   domain.com     |
-       +------------------+                          +------------------+
-                |       .................................        |
-                |______|     Partially Shared State      |_______|
-                       | Room ID: !qporfwt:matrix.org    |
-                       | Servers: matrix.org, domain.com |
-                       | Members:                        |
-                       |  - @alice:matrix.org            |
-                       |  - @bob:domain.com              |
-                       |.................................|
-
-Federation maintains shared state between multiple home servers, such that when an event is
-sent to a room, the home server knows where to forward the event on to, and how to process
-the event. Home servers do not need to have completely shared state in order to participate 
-in a room. State is scoped to a single room, and federation ensures that all home servers 
-have the information they need, even if that means the home server has to request more 
-information from another home server before processing the event.
-
-Room Aliases
-------------
-
-Each room can also have multiple "Room Aliases", which looks like::
-
-  #room_alias:domain
-
-  .. TODO
-      - Need to specify precise grammar for Room IDs
-
-A room alias "points" to a room ID and is the human-readable label by which rooms are
-publicised and discovered.  The room ID the alias is pointing to can be obtained
-by visiting the domain specified. They are case-insensitive. Note that the mapping 
-from a room alias to a room ID is not fixed, and may change over time to point to a 
-different room ID. For this reason, Clients SHOULD resolve the room alias to a room ID 
-once and then use that ID on subsequent requests.
-
-::
-
-          GET    
-   #matrix:domain.com      !aaabaa:matrix.org
-           |                    ^
-           |                    |
-    _______V____________________|____
-   |          domain.com            |
-   | Mappings:                      |
-   | #matrix >> !aaabaa:matrix.org  |
-   | #golf   >> !wfeiofh:sport.com  |
-   | #bike   >> !4rguxf:matrix.org  |
-   |________________________________|
-
-.. TODO kegan
-   - show the actual API rather than pseudo-API?
-
-       
-Identity
---------
-
-Users in Matrix are identified via their user ID. However, existing ID namespaces can also
-be used in order to identify Matrix users. A Matrix "Identity" describes both the user ID
-and any other existing IDs from third party namespaces *linked* to their account.
-
-Matrix users can *link* third-party IDs (3PIDs) such as email addresses, social
-network accounts and phone numbers to their 
-user ID. Linking 3PIDs creates a mapping from a 3PID to a user ID. This mapping
-can then be used by other Matrix users in order to discover other users, according
-to a strict set of privacy permissions.
-
-In order to ensure that the mapping from 3PID to user ID is genuine, a globally federated
-cluster of trusted "Identity Servers" (IS) are used to perform authentication of the 3PID.
-Identity servers are also used to preserve the mapping indefinitely, by replicating the
-mappings across multiple ISes.
-
-Usage of an IS is not required in order for a client application to be part of 
-the Matrix ecosystem. However, by not using an IS, discovery of users is greatly
-impacted.
-
-API Standards
--------------
-
-The mandatory baseline for communication in Matrix is exchanging JSON objects over RESTful
-HTTP APIs. HTTPS is mandated as the baseline for server-server (federation) communication.
-HTTPS is recommended for client-server communication, although HTTP may be supported as a
-fallback to support basic HTTP clients. More efficient optional transports for
-client-server communication will in future be supported as optional extensions - e.g. a
-packed binary encoding over stream-cipher encrypted TCP socket for
-low-bandwidth/low-roundtrip mobile usage.
-
-.. TODO
-  We need to specify capability negotiation for extensible transports
-
-For the default HTTP transport, all API calls use a Content-Type of ``application/json``.
-In addition, all strings MUST be encoded as UTF-8.
-
-Clients are authenticated using opaque ``access_token`` strings (see `Registration and
-Login`_ for details), passed as a querystring parameter on all requests.
-
-.. TODO
-  Need to specify any HMAC or access_token lifetime/ratcheting tricks
-
-Any errors which occur on the Matrix API level 
-MUST return a "standard error response". This is a JSON object which looks like::
-
-  {
-    "errcode": "<error code>",
-    "error": "<error message>"
-  }
-
-The ``error`` string will be a human-readable error message, usually a sentence
-explaining what went wrong. The ``errcode`` string will be a unique string which can be 
-used to handle an error message e.g. ``M_FORBIDDEN``. These error codes should have their 
-namespace first in ALL CAPS, followed by a single _. For example, if there was a custom
-namespace ``com.mydomain.here``, and a ``FORBIDDEN`` code, the error code should look
-like ``COM.MYDOMAIN.HERE_FORBIDDEN``. There may be additional keys depending on 
-the error, but the keys ``error`` and ``errcode`` MUST always be present. 
-
-Some standard error codes are below:
-
-:``M_FORBIDDEN``:
-  Forbidden access, e.g. joining a room without permission, failed login.
-
-:``M_UNKNOWN_TOKEN``:
-  The access token specified was not recognised.
-
-:``M_BAD_JSON``:
-  Request contained valid JSON, but it was malformed in some way, e.g. missing
-  required keys, invalid values for keys.
-
-:``M_NOT_JSON``:
-  Request did not contain valid JSON.
-
-:``M_NOT_FOUND``:
-  No resource was found for this request.
-
-:``M_LIMIT_EXCEEDED``:
-  Too many requests have been sent in a short period of time. Wait a while then
-  try again.
-
-Some requests have unique error codes:
-
-:``M_USER_IN_USE``:
-  Encountered when trying to register a user ID which has been taken.
-
-:``M_ROOM_IN_USE``:
-  Encountered when trying to create a room which has been taken.
-
-:``M_BAD_PAGINATION``:
-  Encountered when specifying bad pagination query parameters.
-
-:``M_LOGIN_EMAIL_URL_NOT_YET``:
-  Encountered when polling for an email link which has not been clicked yet.
-
-The C-S API typically uses ``HTTP POST`` to submit requests. This means these requests are
-not idempotent. The C-S API also allows ``HTTP PUT`` to make requests idempotent. In order
-to use a ``PUT``, paths should be suffixed with ``/{txnId}``. ``{txnId}`` is a
-unique client-generated transaction ID which identifies the request, and is scoped to a given
-Client (identified by that client's ``access_token``). Crucially, it **only** serves to
-identify new requests from retransmits. After the request has finished, the ``{txnId}``
-value should be changed (how is not specified; a monotonically increasing integer is
-recommended). It is preferable to use ``HTTP PUT`` to make sure requests to send messages
-do not get sent more than once should clients need to retransmit requests.
-
-Valid requests look like::
-
-    POST /some/path/here?access_token=secret
-    {
-      "key": "This is a post."
-    }
-
-    PUT /some/path/here/11?access_token=secret
-    {
-      "key": "This is a put with a txnId of 11."
-    }
-
-In contrast, these are invalid requests::
-
-    POST /some/path/here/11?access_token=secret
-    {
-      "key": "This is a post, but it has a txnId."
-    }
-
-    PUT /some/path/here?access_token=secret
-    {
-      "key": "This is a put but it is missing a txnId."
-    }
-
-Receiving live updates on a client
-----------------------------------
-
-Clients can receive new events by long-polling the home server. This will hold open the
-HTTP connection for a short period of time waiting for new events, returning early if an
-event occurs. This is called the `Event Stream`_. All events which are visible to the
-client will appear in the event stream. When the request
-returns, an ``end`` token is included in the response. This token can be used in the next
-request to continue where the client left off.
-
-.. TODO
-  How do we filter the event stream?
-  Do we ever return multiple events in a single request?  Don't we get lots of request
-  setup RTT latency if we only do one event per request? Do we ever support streaming
-  requests? Why not websockets?
-
-When the client first logs in, they will need to initially synchronise with their home
-server. This is achieved via the |initialSync|_ API. This API also returns an ``end``
-token which can be used with the event stream.
-
-Rooms
-=====
-
-Creation
---------
-.. TODO kegan
-  - TODO: Key for invite these users?
-  
-To create a room, a client has to use the |createRoom|_ API. There are various options
-which can be set when creating a room:
-
-``visibility``
-  Type: 
-    String
-  Optional: 
-    Yes
-  Value:
-    Either ``public`` or ``private``.
-  Description:
-    A ``public`` visibility indicates that the room will be shown in the public room list. A
-    ``private`` visibility will hide the room from the public room list. Rooms default to
-    ``public`` visibility if this key is not included.
-
-``room_alias_name``
-  Type: 
-    String
-  Optional: 
-    Yes
-  Value:
-    The room alias localpart.
-  Description:
-    If this is included, a room alias will be created and mapped to the newly created room.
-    The alias will belong on the same home server which created the room, e.g.
-    ``!qadnasoi:domain.com >>> #room_alias_name:domain.com``
-
-``name``
-  Type: 
-    String
-  Optional: 
-    Yes
-  Value:
-    The ``name`` value for the ``m.room.name`` state event.
-  Description:
-    If this is included, an ``m.room.name`` event will be sent into the room to indicate the
-    name of the room. See `Room Events`_ for more information on ``m.room.name``.
-
-``topic``
-  Type: 
-    String
-  Optional: 
-    Yes
-  Value:
-    The ``topic`` value for the ``m.room.topic`` state event.
-  Description:
-    If this is included, an ``m.room.topic`` event will be sent into the room to indicate the
-    topic for the room. See `Room Events`_ for more information on ``m.room.topic``.
-
-``invite``
-  Type:
-    List
-  Optional:
-    Yes
-  Value:
-    A list of user ids to invite.
-  Description:
-    This will tell the server to invite everyone in the list to the newly created room.
-
-Example::
-
-  {
-    "visibility": "public", 
-    "room_alias_name": "the pub",
-    "name": "The Grand Duke Pub",
-    "topic": "All about happy hour"
-  }
-
-The home server will create a ``m.room.create`` event when the room is
-created, which serves as the root of the PDU graph for this room. This
-event also has a ``creator`` key which contains the user ID of the room
-creator. It will also generate several other events in order to manage
-permissions in this room. This includes:
-
- - ``m.room.power_levels`` : Sets the power levels of users.
- - ``m.room.join_rules`` : Whether the room is "invite-only" or not.
- - ``m.room.add_state_level``: The power level required in order to
-   add new state to the room (as opposed to updating exisiting state)
- - ``m.room.send_event_level`` : The power level required in order to
-   send a message in this room.
- - ``m.room.ops_level`` : The power level required in order to kick or
-   ban a user from the room.
-
-See `Room Events`_ for more information on these events.
-
-Modifying aliases
------------------
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO kegan
-    - path to edit aliases 
-    - PUT /directory/room/<room alias>  { room_id : foo }
-    - GET /directory/room/<room alias> { room_id : foo, servers: [a.com, b.com] }
-    - format when retrieving list of aliases. NOT complete list.
-    - format for adding/removing aliases.
-
-Permissions
------------
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO kegan
-    - TODO: What is a power level? How do they work? Defaults / required levels for X. How do they change
-      as people join and leave rooms? What do you do if you get a clash? Examples.
-    - TODO: List all actions which use power levels (sending msgs, inviting users, banning people, etc...)
-    - TODO: Room config - what is the event and what are the keys/values and explanations for them.
-      Link through to respective sections where necessary. How does this tie in with permissions, e.g.
-      give example of creating a read-only room.
-
-Permissions for rooms are done via the concept of power levels - to do any
-action in a room a user must have a suitable power level. 
-
-Power levels for users are defined in ``m.room.power_levels``, where both
-a default and specific users' power levels can be set. By default all users
-have a power level of 0, other than the room creator whose power level defaults to 100.
-Power levels for users are tracked per-room even if the user is not present in 
-the room.
-
-State events may contain a ``required_power_level`` key, which indicates the
-minimum power a user must have before they can update that state key. The only
-exception to this is when a user leaves a room.
-
-To perform certain actions there are additional power level requirements
-defined in the following state events:
-
-- ``m.room.send_event_level`` defines the minimum level for sending non-state 
-  events. Defaults to 50.
-- ``m.room.add_state_level`` defines the minimum level for adding new state,
-  rather than updating existing state. Defaults to 50.
-- ``m.room.ops_level`` defines the minimum levels to ban and kick other users.
-  This defaults to a kick and ban levels of 50 each.
-
-
-Joining rooms
--------------
-.. TODO kegan
-  - TODO: What does the home server have to do to join a user to a room?
-
-Users need to join a room in order to send and receive events in that room. A user can join a
-room by making a request to |/join/<room_alias_or_id>|_ with::
-
-  {}
-
-Alternatively, a user can make a request to |/rooms/<room_id>/join|_ with the same request content.
-This is only provided for symmetry with the other membership APIs: ``/rooms/<room id>/invite`` and
-``/rooms/<room id>/leave``. If a room alias was specified, it will be automatically resolved to
-a room ID, which will then be joined. The room ID that was joined will be returned in response::
-
-  {
-    "room_id": "!roomid:domain"
-  }
-
-The membership state for the joining user can also be modified directly to be ``join``
-by sending the following request to 
-``/rooms/<room id>/state/m.room.member/<url encoded user id>``::
-
-  {
-    "membership": "join"
-  }
-
-See the `Room events`_ section for more information on ``m.room.member``.
-
-After the user has joined a room, they will receive subsequent events in that room. This room
-will now appear as an entry in the |initialSync|_ API.
-
-Some rooms enforce that a user is *invited* to a room before they can join that room. Other
-rooms will allow anyone to join the room even if they have not received an invite.
-
-Inviting users
---------------
-.. TODO kegan
-  - Can invite users to a room if the room config key TODO is set to TODO. Must have required power level.
-  - Outline invite join dance. What is it? Why is it required? How does it work?
-  - What does the home server have to do?
-  - TODO: In what circumstances will direct member editing NOT be equivalent to ``/invite``?
-
-The purpose of inviting users to a room is to notify them that the room exists 
-so they can choose to become a member of that room. Some rooms require that all 
-users who join a room are previously invited to it (an "invite-only" room). 
-Whether a given room is an "invite-only" room is determined by the room config 
-key ``TODO``. It can have one of the following values:
-
- - TODO Room config invite only value explanation
- - TODO Room config free-to-join value explanation
-
-Only users who have a membership state of ``join`` in a room can invite new 
-users to said room. The person being invited must not be in the ``join`` state 
-in the room. The fully-qualified user ID must be specified when inviting a user, 
-as the user may reside on a different home server. To invite a user, send the 
-following request to |/rooms/<room_id>/invite|_, which will manage the 
-entire invitation process::
-
-  {
-    "user_id": "<user id to invite>"
-  }
-
-Alternatively, the membership state for this user in this room can be modified 
-directly by sending the following request to 
-``/rooms/<room id>/state/m.room.member/<url encoded user id>``::
-
-  {
-    "membership": "invite"
-  }
-
-See the `Room events`_ section for more information on ``m.room.member``.
-
-Leaving rooms
--------------
-.. TODO kegan
-  - TODO: Grace period before deletion?
-  - TODO: Under what conditions should a room NOT be purged?
-
-
-A user can leave a room to stop receiving events for that room. A user must have
-joined the room before they are eligible to leave the room. If the room is an
-"invite-only" room, they will need to be re-invited before they can re-join the room.
-To leave a room, a request should be made to |/rooms/<room_id>/leave|_ with::
-
-  {}
-
-Alternatively, the membership state for this user in this room can be modified 
-directly by sending the following request to 
-``/rooms/<room id>/state/m.room.member/<url encoded user id>``::
-
-  {
-    "membership": "leave"
-  }
-
-See the `Room events`_ section for more information on ``m.room.member``.
-
-Once a user has left a room, that room will no longer appear on the |initialSync|_
-API. Be aware that leaving a room is not equivalent to have never been
-in that room. A user who has previously left a room still maintains some residual state in
-that room. Their membership state will be marked as ``leave``. This contrasts with
-a user who has *never been invited or joined to that room* who will not have any
-membership state for that room. 
-
-If all members in a room leave, that room becomes eligible for deletion. 
-
-Banning users in a room
------------------------
-A user may decide to ban another user in a room. 'Banning' forces the target user
-to leave the room and prevents them from re-joining the room. A banned user will
-not be treated as a joined user, and so will not be able to send or receive events
-in the room. In order to ban someone, the user performing the ban MUST have the 
-required power level. To ban a user, a request should be made to 
-|/rooms/<room_id>/ban|_ with::
-
-  {
-    "user_id": "<user id to ban"
-    "reason": "string: <reason for the ban>"
-  }
-  
-Banning a user adjusts the banned member's membership state to ``ban`` and adjusts
-the power level of this event to a level higher than the banned person. Like 
-with other membership changes, a user can directly adjust the target member's 
-state, by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``::
-
-  {
-    "membership": "ban"
-  }
-
-Events in a room
-----------------
-Room events can be split into two categories:
-
-:State Events:
-  These are events which replace events that came before it, depending on a set of unique keys.
-  These keys are the event ``type`` and a ``state_key``. Events with the same set of keys will
-  be overwritten. Typically, state events are used to store state, hence their name.
-
-:Non-state events:
-  These are events which cannot be overwritten after sending. The list of events continues
-  to grow as more events are sent. As this list grows, it becomes necessary to
-  provide a mechanism for navigating this list. Pagination APIs are used to view the list
-  of historical non-state events. Typically, non-state events are used to send messages.
-
-This specification outlines several events, all with the event type prefix ``m.``. However,
-applications may wish to add their own type of event, and this can be achieved using the 
-REST API detailed in the following sections. If new events are added, the event ``type`` 
-key SHOULD follow the Java package naming convention, e.g. ``com.example.myapp.event``. 
-This ensures event types are suitably namespaced for each application and reduces the 
-risk of clashes.
-
-State events
-------------
-State events can be sent by ``PUT`` ing to |/rooms/<room_id>/state/<event_type>/<state_key>|_.
-These events will be overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all match.
-If the state event has no ``state_key``, it can be omitted from the path. These requests 
-**cannot use transaction IDs** like other ``PUT`` paths because they cannot be differentiated 
-from the ``state_key``. Furthermore, ``POST`` is unsupported on state paths. Valid requests
-look like::
-
-  PUT /rooms/!roomid:domain/state/m.example.event
-  { "key" : "without a state key" }
-
-  PUT /rooms/!roomid:domain/state/m.another.example.event/foo
-  { "key" : "with 'foo' as the state key" }
-
-In contrast, these requests are invalid::
-
-  POST /rooms/!roomid:domain/state/m.example.event/
-  { "key" : "cannot use POST here" }
-
-  PUT /rooms/!roomid:domain/state/m.another.example.event/foo/11
-  { "key" : "txnIds are not supported" }
-
-Care should be taken to avoid setting the wrong ``state key``::
-
-  PUT /rooms/!roomid:domain/state/m.another.example.event/11
-  { "key" : "with '11' as the state key, but was probably intended to be a txnId" }
-
-The ``state_key`` is often used to store state about individual users, by using the user ID as the
-``state_key`` value. For example::
-
-  PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Adomain.com
-  { "animal" : "cat", "reason": "fluffy" }
-
-In some cases, there may be no need for a ``state_key``, so it can be omitted::
-
-  PUT /rooms/!roomid:domain/state/m.room.bgd.color
-  { "color": "red", "hex": "#ff0000" }
-
-See `Room Events`_ for the ``m.`` event specification.
-
-Non-state events
-----------------
-Non-state events can be sent by sending a request to |/rooms/<room_id>/send/<event_type>|_.
-These requests *can* use transaction IDs and ``PUT``/``POST`` methods. Non-state events 
-allow access to historical events and pagination, making it best suited for sending messages.
-For example::
-
-  POST /rooms/!roomid:domain/send/m.custom.example.message
-  { "text": "Hello world!" }
-
-  PUT /rooms/!roomid:domain/send/m.custom.example.message/11
-  { "text": "Goodbye world!" }
-
-See `Room Events`_ for the ``m.`` event specification.
-
-Syncing rooms
--------------
-.. NOTE::
-  This section is a work in progress.
-
-When a client logs in, they may have a list of rooms which they have already joined. These rooms
-may also have a list of events associated with them. The purpose of 'syncing' is to present the
-current room and event information in a convenient, compact manner. The events returned are not
-limited to room events; presence events will also be returned. There are two APIs provided:
-
- - |initialSync|_ : A global sync which will present room and event information for all rooms
-   the user has joined.
-
- - |/rooms/<room_id>/initialSync|_ : A sync scoped to a single room. Presents room and event
-   information for this room only.
-
-.. TODO kegan
-  - TODO: JSON response format for both types
-  - TODO: when would you use global? when would you use scoped?
-
-Getting events for a room
--------------------------
-There are several APIs provided to ``GET`` events for a room:
-
-``/rooms/<room id>/state/<event type>/<state key>``
-  Description:
-    Get the state event identified.
-  Response format:
-    A JSON object representing the state event **content**.
-  Example:
-    ``/rooms/!room:domain.com/state/m.room.name`` returns ``{ "name": "Room name" }``
-
-|/rooms/<room_id>/state|_
-  Description:
-    Get all state events for a room.
-  Response format:
-    ``[ { state event }, { state event }, ... ]``
-  Example:
-    TODO
-
-
-|/rooms/<room_id>/members|_
-  Description:
-    Get all ``m.room.member`` state events.
-  Response format:
-    ``{ "start": "<token>", "end": "<token>", "chunk": [ { m.room.member event }, ... ] }``
-  Example:
-    TODO
-
-|/rooms/<room_id>/messages|_
-  Description:
-    Get all ``m.room.message`` and ``m.room.member`` events. This API supports pagination
-	using ``from`` and ``to`` query parameters, coupled with the ``start`` and ``end``
-	tokens from an |initialSync|_ API.
-  Response format:
-    ``{ "start": "<token>", "end": "<token>" }``
-  Example:
-    TODO
-    
-|/rooms/<room_id>/initialSync|_
-  Description:
-    Get all relevant events for a room. This includes state events, paginated non-state
-    events and presence events.
-  Response format:
-    `` { TODO } ``
-  Example:
-    TODO
-
-
-Room Events
-===========
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO dave?
-  - voip events?
-
-This specification outlines several standard event types, all of which are
-prefixed with ``m.``
-
-``m.room.name``
-  Summary:
-    Set the human-readable name for the room.
-  Type: 
-    State event
-  JSON format:
-    ``{ "name" : "string" }``
-  Example:
-    ``{ "name" : "My Room" }``
-  Description:
-    A room has an opaque room ID which is not human-friendly to read. A room alias is
-    human-friendly, but not all rooms have room aliases. The room name is a human-friendly
-    string designed to be displayed to the end-user. The room name is not *unique*, as
-    multiple rooms can have the same room name set. The room name can also be set when 
-    creating a room using |createRoom|_ with the ``name`` key.
-
-``m.room.topic``
-  Summary:
-    Set a topic for the room.
-  Type: 
-    State event
-  JSON format:
-    ``{ "topic" : "string" }``
-  Example:
-    ``{ "topic" : "Welcome to the real world." }``
-  Description:
-    A topic is a short message detailing what is currently being discussed in the room. 
-    It can also be used as a way to display extra information about the room, which may
-    not be suitable for the room name. The room topic can also be set when creating a
-    room using |createRoom|_ with the ``topic`` key.
-
-``m.room.member``
-  Summary:
-    The current membership state of a user in the room.
-  Type: 
-    State event
-  JSON format:
-    ``{ "membership" : "enum[ invite|join|leave|ban ]" }``
-  Example:
-    ``{ "membership" : "join" }``
-  Description:
-    Adjusts the membership state for a user in a room. It is preferable to use the
-    membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions
-    rather than adjusting the state directly as there are a restricted set of valid
-    transformations. For example, user A cannot force user B to join a room, and trying
-    to force this state change directly will fail. See the `Rooms`_ section for how to 
-    use the membership APIs.
-
-``m.room.create``
-  Summary:
-    The first event in the room.
-  Type: 
-    State event
-  JSON format:
-    ``{ "creator": "string"}``
-  Example:
-    ``{ "creator": "@user:example.com" }``
-  Description:
-    This is the first event in a room and cannot be changed. It acts as the 
-    root of all other events.
-
-``m.room.join_rules``
-  Summary:
-    Descripes how/if people are allowed to join.
-  Type: 
-    State event
-  JSON format:
-    ``{ "join_rule": "enum [ public|knock|invite|private ]" }``
-  Example:
-    ``{ "join_rule": "public" }``
-  Description:
-    TODO : Use docs/models/rooms.rst
-   
-``m.room.power_levels``
-  Summary:
-    Defines the power levels of users in the room.
-  Type: 
-    State event
-  JSON format:
-    ``{ "<user_id>": <int>, ..., "default": <int>}``
-  Example:
-    ``{ "@user:example.com": 5, "@user2:example.com": 10, "default": 0 }`` 
-  Description:
-    If a user is in the list, then they have the associated power level. 
-    Otherwise they have the default level. If not ``default`` key is supplied,
-    it is assumed to be 0.
-
-``m.room.add_state_level``
-  Summary:
-    Defines the minimum power level a user needs to add state.
-  Type: 
-    State event
-  JSON format:
-    ``{ "level": <int> }``
-  Example:
-    ``{ "level": 5 }``
-  Description:
-    To add a new piece of state to the room a user must have the given power 
-    level. This does not apply to updating current state, which is goverened
-    by the ``required_power_level`` event key.
-    
-``m.room.send_event_level``
-  Summary:
-    Defines the minimum power level a user needs to send an event.
-  Type: 
-    State event
-  JSON format:
-    ``{ "level": <int> }``
-  Example:
-    ``{ "level": 0 }``
-  Description:
-    To send a new event into the room a user must have at least this power 
-    level. This allows ops to make the room read only by increasing this level,
-    or muting individual users by lowering their power level below this
-    threshold.
-
-``m.room.ops_levels``
-  Summary:
-    Defines the minimum power levels that a user must have before they can 
-    kick and/or ban other users.
-  Type: 
-    State event
-  JSON format:
-    ``{ "ban_level": <int>, "kick_level": <int> }``
-  Example:
-    ``{ "ban_level": 5, "kick_level": 5 }``
-  Description:
-    This defines who can ban and/or kick people in the room. Most of the time
-    ``ban_level`` will be greater than or equal to ``kick_level`` since 
-    banning is more severe than kicking.
-
-``m.room.aliases``
-  Summary:
-    These state events are used to inform the room about what room aliases it has.
-  Type:
-    State event
-  JSON format:
-    ``{ "aliases": ["string", ...] }``
-  Example:
-    ``{ "aliases": ["#foo:example.com"] }``
-  Description:
-    A server `may` inform the room that it has added or removed an alias for 
-    the room. This is purely for informational purposes and may become stale.
-    Clients `should` check that the room alias is still valid before using it.
-    The ``state_key`` of the event is the homeserver which owns the room 
-    alias.
-
-``m.room.message``
-  Summary:
-    A message.
-  Type: 
-    Non-state event
-  JSON format:
-    ``{ "msgtype": "string" }``
-  Example:
-    ``{ "msgtype": "m.text", "body": "Testing" }``
-  Description:
-    This event is used when sending messages in a room. Messages are not limited to be text.
-    The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc.
-    Whilst not required, the ``body`` key SHOULD be used with every kind of ``msgtype`` as
-    a fallback mechanism when a client cannot render the message. For more information on 
-    the types of messages which can be sent, see `m.room.message msgtypes`_.
-
-``m.room.message.feedback``
-  Summary:
-    A receipt for a message.
-  Type: 
-    Non-state event
-  JSON format:
-    ``{ "type": "enum [ delivered|read ]", "target_event_id": "string" }``
-  Example:
-    ``{ "type": "delivered", "target_event_id": "e3b2icys" }``
-  Description:
-    Feedback events are events sent to acknowledge a message in some way. There are two
-    supported acknowledgements: ``delivered`` (sent when the event has been received) and 
-    ``read`` (sent when the event has been observed by the end-user). The ``target_event_id``
-    should reference the ``m.room.message`` event being acknowledged. 
-
-m.room.message msgtypes
------------------------
-Each ``m.room.message`` MUST have a ``msgtype`` key which identifies the type of
-message being sent. Each type has their own required and optional keys, as outlined
-below:
-
-``m.text``
-  Required keys:
-    - ``body`` : "string" - The body of the message.
-  Optional keys:
-    None.
-  Example:
-    ``{ "msgtype": "m.text", "body": "I am a fish" }``
-
-``m.emote``
-  Required keys:
-    - ``body`` : "string" - The emote action to perform.
-  Optional keys:
-    None.
-  Example:
-    ``{ "msgtype": "m.emote", "body": "tries to come up with a witty explanation" }``
-
-``m.image``
-  Required keys:
-    - ``url`` : "string" - The URL to the image.
-  Optional keys:
-    - ``info`` : "string" - info : JSON object (ImageInfo) - The image info for image 
-      referred to in ``url``.
-    - ``thumbnail_url`` : "string" - The URL to the thumbnail.
-    - ``thumbnail_info`` : JSON object (ImageInfo) - The image info for the image 
-      referred to in ``thumbnail_url``.
-    - ``body`` : "string" - The alt text of the image, or some kind of content 
-      description for accessibility e.g. "image attachment".
-
-  ImageInfo: 
-    Information about an image::
-    
-      { 
-        "size" : integer (size of image in bytes),
-        "w" : integer (width of image in pixels),
-        "h" : integer (height of image in pixels),
-        "mimetype" : "string (e.g. image/jpeg)",
-      }
-
-``m.audio``
-  Required keys:
-    - ``url`` : "string" - The URL to the audio.
-  Optional keys:
-    - ``info`` : JSON object (AudioInfo) - The audio info for the audio referred to in 
-      ``url``.
-    - ``body`` : "string" - A description of the audio e.g. "Bee Gees - 
-      Stayin' Alive", or some kind of content description for accessibility e.g. 
-      "audio attachment".
-  AudioInfo: 
-    Information about a piece of audio::
-
-      {
-        "mimetype" : "string (e.g. audio/aac)",
-        "size" : integer (size of audio in bytes),
-        "duration" : integer (duration of audio in milliseconds),
-      }
-
-``m.video``
-  Required keys:
-    - ``url`` : "string" - The URL to the video.
-  Optional keys:
-    - ``info`` : JSON object (VideoInfo) - The video info for the video referred to in 
-      ``url``.
-    - ``body`` : "string" - A description of the video e.g. "Gangnam style", 
-      or some kind of content description for accessibility e.g. "video attachment".
-
-  VideoInfo: 
-    Information about a video::
-
-      {
-        "mimetype" : "string (e.g. video/mp4)",
-        "size" : integer (size of video in bytes),
-        "duration" : integer (duration of video in milliseconds),
-        "w" : integer (width of video in pixels),
-        "h" : integer (height of video in pixels),
-        "thumbnail_url" : "string (URL to image)",
-        "thumbanil_info" : JSON object (ImageInfo)
-      }
-
-``m.location``
-  Required keys:
-    - ``geo_uri`` : "string" - The geo URI representing the location.
-  Optional keys:
-    - ``thumbnail_url`` : "string" - The URL to a thumnail of the location being 
-      represented.
-    - ``thumbnail_info`` : JSON object (ImageInfo) - The image info for the image 
-      referred to in ``thumbnail_url``.
-    - ``body`` : "string" - A description of the location e.g. "Big Ben, 
-      London, UK", or some kind of content description for accessibility e.g. 
-      "location attachment".
-
-The following keys can be attached to any ``m.room.message``:
-
-  Optional keys:
-    - ``sender_ts`` : integer - A timestamp (ms resolution) representing the 
-      wall-clock time when the message was sent from the client.
-
-Presence
-========
-.. NOTE::
-  This section is a work in progress.
-
-Each user has the concept of presence information. This encodes the
-"availability" of that user, suitable for display on other user's clients. This
-is transmitted as an ``m.presence`` event and is one of the few events which
-are sent *outside the context of a room*. The basic piece of presence information 
-is represented by the ``presence`` key, which is an enum of one of the following:
-
-  - ``online`` : The default state when the user is connected to an event stream.
-  - ``unavailable`` : The user is not reachable at this time.
-  - ``offline`` : The user is not connected to an event stream.
-  - ``free_for_chat`` : The user is generally willing to receive messages 
-    moreso than default.
-  - ``hidden`` : TODO. Behaves as offline, but allows the user to see the client 
-    state anyway and generally interact with client features.
-
-This basic ``presence`` field applies to the user as a whole, regardless of how many
-client devices they have connected. The home server should synchronise this
-status choice among multiple devices to ensure the user gets a consistent
-experience.
-
-In addition, the server maintains a timestamp of the last time it saw an active
-action from the user; either sending a message to a room, or changing presence
-state from a lower to a higher level of availability (thus: changing state from
-``unavailable`` to ``online`` will count as an action for being active, whereas
-in the other direction will not). This timestamp is presented via a key called
-``last_active_ago``, which gives the relative number of miliseconds since the
-message is generated/emitted, that the user was last seen active.
-
-Idle Time
----------
-As well as the basic ``presence`` field, the presence information can also show
-a sense of an "idle timer". This should be maintained individually by the
-user's clients, and the home server can take the highest reported time as that
-to report. When a user is offline, the home server can still report when the
-user was last seen online.
-
-Transmission
-------------
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO:
-  - Transmitted as an EDU.
-  - Presence lists determine who to send to.
-
-Presence List
--------------
-Each user's home server stores a "presence list" for that user. This stores a
-list of other user IDs the user has chosen to add to it. To be added to this 
-list, the user being added must receive permission from the list owner. Once
-granted, both user's HS(es) store this information. Since such subscriptions
-are likely to be bidirectional, HSes may wish to automatically accept requests
-when a reverse subscription already exists.
-
-Presence and Permissions
-------------------------
-For a viewing user to be allowed to see the presence information of a target
-user, either:
-
- - The target user has allowed the viewing user to add them to their presence
-   list, or
- - The two users share at least one room in common
-
-In the latter case, this allows for clients to display some minimal sense of
-presence information in a user list for a room.
-
-Typing notifications
-====================
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO Leo
-    - what is the event type. Are they bundled with other event types? If so, which.
-    - what are the valid keys / values. What do they represent. Any gotchas?
-    - Timeouts. How do they work, who sets them and how do they expire. Does one
-      have priority over another? Give examples.
-
-Voice over IP
-=============
-Matrix can also be used to set up VoIP calls. This is part of the core specification,
-although is still in a very early stage. Voice (and video) over Matrix is based on
-the WebRTC standards.
-
-Call events are sent to a room, like any other event. This means that clients
-must only send call events to rooms with exactly two participants as currently
-the WebRTC standard is based around two-party communication.
-
-Events
-------
-``m.call.invite``
-This event is sent by the caller when they wish to establish a call.
-
-  Required keys:
-    - ``call_id`` : "string" - A unique identifier for the call
-    - ``offer`` : "offer object" - The session description
-    - ``version`` : "integer" - The version of the VoIP specification this
-                                message adheres to. This specification is
-                                version 0.
-    - ``lifetime`` : "integer" - The time in milliseconds that the invite is
-                                 valid for. Once the invite age exceeds this
-                                 value, clients should discard it. They
-                                 should also no longer show the call as
-                                 awaiting an answer in the UI.
-      
-  Optional keys:
-    None.
-  Example:
-    ``{ "version" : 0, "call_id": "12345", "offer": { "type" : "offer", "sdp" : "v=0\r\no=- 6584580628695956864 2 IN IP4 127.0.0.1[...]" } }``
-
-``Offer Object``
-  Required keys:
-    - ``type`` : "string" - The type of session description, in this case 'offer'
-    - ``sdp`` : "string" - The SDP text of the session description
-
-``m.call.candidates``
-This event is sent by callers after sending an invite and by the callee after answering.
-Its purpose is to give the other party additional ICE candidates to try using to
-communicate.
-
-  Required keys:
-    - ``call_id`` : "string" - The ID of the call this event relates to
-    - ``version`` : "integer" - The version of the VoIP specification this messages
-                                adheres to. his specification is version 0.
-    - ``candidates`` : "array of candidate objects" - Array of object describing the candidates.
-
-``Candidate Object``
-
-  Required Keys:
-    - ``sdpMid`` : "string" - The SDP media type this candidate is intended for.
-    - ``sdpMLineIndex`` : "integer" - The index of the SDP 'm' line this
-                                      candidate is intended for
-    - ``candidate`` : "string" - The SDP 'a' line of the candidate
-
-``m.call.answer``
-
-  Required keys:
-    - ``call_id`` : "string" - The ID of the call this event relates to
-    - ``version`` : "integer" - The version of the VoIP specification this messages
-    - ``answer`` : "answer object" - Object giving the SDK answer
-
-``Answer Object``
-
-  Required keys:
-    - ``type`` : "string" - The type of session description. 'answer' in this case.
-    - ``sdp`` : "string" - The SDP text of the session description
-
-``m.call.hangup``
-Sent by either party to signal their termination of the call. This can be sent either once
-the call has has been established or before to abort the call.
-
-  Required keys:
-    - ``call_id`` : "string" - The ID of the call this event relates to
-    - ``version`` : "integer" - The version of the VoIP specification this messages
-
-Message Exchange
-----------------
-A call is set up with messages exchanged as follows:
-
-::
-
-   Caller                   Callee
- m.call.invite ----------->
- m.call.candidate -------->
- [more candidates events]
-                         User answers call
-                  <------ m.call.answer
-               [...]
-                  <------ m.call.hangup
-                  
-Or a rejected call:
-
-::
-
-   Caller                   Callee
- m.call.invite ----------->
- m.call.candidate -------->
- [more candidates events]
-                        User rejects call
-                 <------- m.call.hangup
-
-Calls are negotiated according to the WebRTC specification.
-
-
-Glare
------
-This specification aims to address the problem of two users calling each other
-at roughly the same time and their invites crossing on the wire. It is a far
-better experience for the users if their calls are connected if it is clear
-that their intention is to set up a call with one another.
-
-In Matrix, calls are to rooms rather than users (even if those rooms may only
-contain one other user) so we consider calls which are to the same room.
-
-The rules for dealing with such a situation are as follows:
-
- - If an invite to a room is received whilst the client is preparing to send an
-   invite to the same room, the client should cancel its outgoing call and
-   instead automatically accept the incoming call on behalf of the user.
- - If an invite to a room is received after the client has sent an invite to the
-   same room and is waiting for a response, the client should perform a
-   lexicographical comparison of the call IDs of the two calls and use the
-   lesser of the two calls, aborting the greater. If the incoming call is the
-   lesser, the client should accept this call on behalf of the user.
-
-The call setup should appear seamless to the user as if they had simply placed
-a call and the other party had accepted. Thusly, any media stream that had been
-setup for use on a call should be transferred and used for the call that
-replaces it.
- 
-Profiles
-========
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  - Metadata extensibility
-  - Changing profile info generates m.presence events ("presencelike")
-  - keys on m.presence are optional, except presence which is required
-  - m.room.member is populated with the current displayname at that point in time.
-  - That is added by the HS, not you.
-  - Display name changes also generates m.room.member with displayname key f.e. room
-    the user is in.
-
-Internally within Matrix users are referred to by their user ID, which is typically
-a compact unique identifier. Profiles grant users the ability to see human-readable 
-names for other users that are in some way meaningful to them. Additionally, 
-profiles can publish additional information, such as the user's age or location.
-
-A Profile consists of a display name, an avatar picture, and a set of other 
-metadata fields that the user may wish to publish (email address, phone
-numbers, website URLs, etc...). This specification puts no requirements on the 
-display name other than it being a valid unicode string.
-
-
-
-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 procedure as login, but the path requests are sent to are
-different.
-
-The registration/login process breaks down into the following:
-  1. Determine the requirements for logging in.
-  2. Submit the login stage credentials.
-  3. Get credentials or be told the next stage in the login process and repeat 
-     step 2.
-     
-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::
-
-  The client can login via 3 paths: 1a and 1b, 2a and 2b, or 3. The client should
-  select one of these 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>"
-      }
-    ]
-  }
-
-After the login 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 a login has multiple requests, the home server may wish to create a session. If
-a home server responds with a 'session' key to a request, clients MUST submit it in 
-subsequent requests until the login 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.
-
-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.
-
-Identity
-========
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO Dave
-  - 3PIDs and identity server, functions
-
-Federation
-==========
-
-Federation is the term used to describe how to communicate between Matrix home 
-servers. Federation is a mechanism by which two home servers can exchange
-Matrix event messages, both as a real-time push of current events, and as a
-historic fetching mechanism to synchronise past history for clients to view. It
-uses HTTPS connections between each pair of servers involved as the underlying
-transport. Messages are exchanged between servers in real-time by active pushing
-from each server's HTTP client into the server of the other. Queries to fetch
-historic data for the purpose of back-filling scrollback buffers and the like
-can also be performed. Currently routing of messages between homeservers is full
-mesh (like email) - however, fan-out refinements to this design are currently
-under consideration.
-
-There are three main kinds of communication that occur between home servers:
-
-:Queries:
-   These are single request/response interactions between a given pair of
-   servers, initiated by one side sending an HTTPS GET request to obtain some
-   information, and responded by the other. They are not persisted and contain
-   no long-term significant history. They simply request a snapshot state at the
-   instant the query is made.
-
-:Ephemeral Data Units (EDUs):
-   These are notifications of events that are pushed from one home server to
-   another. They are not persisted and contain no long-term significant history,
-   nor does the receiving home server have to reply to them.
-
-:Persisted Data Units (PDUs):
-   These are notifications of events that are broadcast from one home server to
-   any others that are interested in the same "context" (namely, a Room ID).
-   They are persisted to long-term storage and form the record of history for
-   that context.
-
-EDUs and PDUs are further wrapped in an envelope called a Transaction, which is 
-transferred from the origin to the destination home server using an HTTP PUT request.
-
-
-Transactions
-------------
-.. WARNING::
-  This section may be misleading or inaccurate.
-
-The transfer of EDUs and PDUs between home servers is performed by an exchange
-of Transaction messages, which are encoded as JSON objects, passed over an 
-HTTP PUT request. A Transaction is meaningful only to the pair of home servers that 
-exchanged it; they are not globally-meaningful.
-
-Each transaction has:
- - An opaque transaction ID.
- - A timestamp (UNIX epoch time in milliseconds) generated by its origin server.
- - An origin and destination server name.
- - A list of "previous IDs".
- - A list of PDUs and EDUs - the actual message payload that the Transaction carries.
- 
-``origin``
-  Type: 
-    String
-  Description:
-    DNS name of homeserver making this transaction.
-    
-``ts``
-  Type: 
-    Integer
-  Description:
-    Timestamp in milliseconds on originating homeserver when this transaction 
-    started.
-    
-``previous_ids``
-  Type:
-    List of strings
-  Description:
-    List of transactions that were sent immediately prior to this transaction.
-    
-``pdus``
-  Type:
-    List of Objects.
-  Description:
-    List of updates contained in this transaction.
-
-::
-
- {
-  "transaction_id":"916d630ea616342b42e98a3be0b74113",
-  "ts":1404835423000,
-  "origin":"red",
-  "destination":"blue",
-  "prev_ids":["e1da392e61898be4d2009b9fecce5325"],
-  "pdus":[...],
-  "edus":[...]
- }
-
-The ``prev_ids`` field contains a list of previous transaction IDs that
-the ``origin`` server has sent to this ``destination``. Its purpose is to act as a
-sequence checking mechanism - the destination server can check whether it has
-successfully received that Transaction, or ask for a retransmission if not.
-
-The ``pdus`` field of a transaction is a list, containing zero or more PDUs.[*]
-Each PDU is itself a JSON object containing a number of keys, the exact details of
-which will vary depending on the type of PDU. Similarly, the ``edus`` field is
-another list containing the EDUs. This key may be entirely absent if there are
-no EDUs to transfer.
-
-(* Normally the PDU list will be non-empty, but the server should cope with
-receiving an "empty" transaction, as this is useful for informing peers of other
-transaction IDs they should be aware of. This effectively acts as a push
-mechanism to encourage peers to continue to replicate content.)
-
-PDUs and EDUs
--------------
-.. WARNING::
-  This section may be misleading or inaccurate.
-
-All PDUs have:
- - An ID
- - A context
- - A declaration of their type
- - A list of other PDU IDs that have been seen recently on that context (regardless of which origin
-   sent them)
-
-``context``
-  Type:
-    String
-  Description:
-    Event context identifier
-    
-``origin``
-  Type:
-    String
-  Description:
-    DNS name of homeserver that created this PDU.
-    
-``pdu_id``
-  Type:
-    String
-  Description:
-    Unique identifier for PDU within the context for the originating homeserver
-
-``ts``
-  Type:
-    Integer
-  Description:
-    Timestamp in milliseconds on originating homeserver when this PDU was created.
-
-``pdu_type``
-  Type:
-    String
-  Description:
-    PDU event type.
-
-``prev_pdus``
-  Type:
-    List of pairs of strings
-  Description:
-    The originating homeserver and PDU ids of the most recent PDUs the 
-    homeserver was aware of for this context when it made this PDU.
-
-``depth``
-  Type:
-    Integer
-  Description:
-    The maximum depth of the previous PDUs plus one.
-
-
-.. TODO paul
-  [[TODO(paul): Update this structure so that 'pdu_id' is a two-element
-  [origin,ref] pair like the prev_pdus are]]
-  
-
-For state updates:
-
-``is_state``
-  Type:
-    Boolean
-  Description:
-    True if this PDU is updating state.
-    
-``state_key``
-  Type:
-    String
-  Description:
-    Optional key identifying the updated state within the context.
-    
-``power_level``
-  Type:
-    Integer
-  Description:
-    The asserted power level of the user performing the update.
-    
-``min_update``
-  Type:
-    Integer
-  Description:
-    The required power level needed to replace this update.
-
-``prev_state_id``
-  Type:
-    String
-  Description:
-    PDU event type.
-    
-``prev_state_origin``
-  Type:
-    String
-  Description:
-    The PDU id of the update this replaces.
-    
-``user``
-  Type:
-    String
-  Description:
-    The user updating the state.
-
-::
-
- {
-  "pdu_id":"a4ecee13e2accdadf56c1025af232176",
-  "context":"#example.green",
-  "origin":"green",
-  "ts":1404838188000,
-  "pdu_type":"m.text",
-  "prev_pdus":[["blue","99d16afbc857975916f1d73e49e52b65"]],
-  "content":...
-  "is_state":false
- }
-
-In contrast to Transactions, it is important to note that the ``prev_pdus``
-field of a PDU refers to PDUs that any origin server has sent, rather than
-previous IDs that this ``origin`` has sent. This list may refer to other PDUs sent
-by the same origin as the current one, or other origins.
-
-Because of the distributed nature of participants in a Matrix conversation, it
-is impossible to establish a globally-consistent total ordering on the events.
-However, by annotating each outbound PDU at its origin with IDs of other PDUs it
-has received, a partial ordering can be constructed allowing causality
-relationships to be preserved. A client can then display these messages to the
-end-user in some order consistent with their content and ensure that no message
-that is semantically in reply of an earlier one is ever displayed before it.
-
-PDUs fall into two main categories: those that deliver Events, and those that
-synchronise State. For PDUs that relate to State synchronisation, additional
-keys exist to support this:
-
-::
-
- {...,
-  "is_state":true,
-  "state_key":TODO
-  "power_level":TODO
-  "prev_state_id":TODO
-  "prev_state_origin":TODO}
-
-.. TODO paul
-  [[TODO(paul): At this point we should probably have a long description of how
-  State management works, with descriptions of clobbering rules, power levels, etc
-  etc... But some of that detail is rather up-in-the-air, on the whiteboard, and
-  so on. This part needs refining. And writing in its own document as the details
-  relate to the server/system as a whole, not specifically to server-server
-  federation.]]
-
-EDUs, by comparison to PDUs, do not have an ID, a context, or a list of
-"previous" IDs. The only mandatory fields for these are the type, origin and
-destination home server names, and the actual nested content.
-
-::
-
- {"edu_type":"m.presence",
-  "origin":"blue",
-  "destination":"orange",
-  "content":...}
-  
-  
-Protocol URLs
-=============
-.. WARNING::
-  This section may be misleading or inaccurate.
-
-All these URLs are namespaced within a prefix of::
-
-  /_matrix/federation/v1/...
-
-For active pushing of messages representing live activity "as it happens"::
-
-  PUT .../send/:transaction_id/
-    Body: JSON encoding of a single Transaction
-    Response: TODO
-
-The transaction_id path argument will override any ID given in the JSON body.
-The destination name will be set to that of the receiving server itself. Each
-embedded PDU in the transaction body will be processed.
-
-
-To fetch a particular PDU::
-
-  GET .../pdu/:origin/:pdu_id/
-    Response: JSON encoding of a single Transaction containing one PDU
-
-Retrieves a given PDU from the server. The response will contain a single new
-Transaction, inside which will be the requested PDU.
-  
-
-To fetch all the state of a given context::
-
-  GET .../state/:context/
-    Response: JSON encoding of a single Transaction containing multiple PDUs
-
-Retrieves a snapshot of the entire current state of the given context. The
-response will contain a single Transaction, inside which will be a list of
-PDUs that encode the state.
-
-To backfill events on a given context::
-
-  GET .../backfill/:context/
-    Query args: v, limit
-    Response: JSON encoding of a single Transaction containing multiple PDUs
-
-Retrieves a sliding-window history of previous PDUs that occurred on the
-given context. Starting from the PDU ID(s) given in the "v" argument, the
-PDUs that preceeded it are retrieved, up to a total number given by the
-"limit" argument. These are then returned in a new Transaction containing all
-of the PDUs.
-
-
-To stream events all the events::
-
-  GET .../pull/
-    Query args: origin, v
-    Response: JSON encoding of a single Transaction consisting of multiple PDUs
-
-Retrieves all of the transactions later than any version given by the "v"
-arguments.
-
-
-To make a query::
-
-  GET .../query/:query_type
-    Query args: as specified by the individual query types
-    Response: JSON encoding of a response object
-
-Performs a single query request on the receiving home server. The Query Type
-part of the path specifies the kind of query being made, and its query
-arguments have a meaning specific to that kind of query. The response is a
-JSON-encoded object whose meaning also depends on the kind of query.
-
-Backfilling
------------
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  - What it is, when is it used, how is it done
-
-SRV Records
------------
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  - Why it is needed
-
-Security
-========
-
-.. NOTE::
-  This section is a work in progress.
-
-Threat Model
-------------
-
-Denial of Service
-~~~~~~~~~~~~~~~~~
-
-The attacker could attempt to prevent delivery of messages to or from the
-victim in order to:
-
-* Disrupt service or marketing campaign of a commercial competitor.
-* Censor a discussion or censor a participant in a discussion.
-* Perform general vandalism.
-
-Threat: Resource Exhaustion
-+++++++++++++++++++++++++++
-
-An attacker could cause the victims server to exhaust a particular resource
-(e.g. open TCP connections, CPU, memory, disk storage)
-
-Threat: Unrecoverable Consistency Violations
-++++++++++++++++++++++++++++++++++++++++++++
-
-An attacker could send messages which created an unrecoverable "split-brain"
-state in the cluster such that the victim's servers could no longer dervive a
-consistent view of the chatroom state.
-
-Threat: Bad History
-+++++++++++++++++++
-
-An attacker could convince the victim to accept invalid messages which the
-victim would then include in their view of the chatroom history. Other servers
-in the chatroom would reject the invalid messages and potentially reject the
-victims messages as well since they depended on the invalid messages.
-
-.. TODO
-  Track trustworthiness of HS or users based on if they try to pretend they
-  haven't seen recent events, and fake a splitbrain... --M
-
-Threat: Block Network Traffic
-+++++++++++++++++++++++++++++
-
-An attacker could try to firewall traffic between the victim's server and some
-or all of the other servers in the chatroom.
-
-Threat: High Volume of Messages
-+++++++++++++++++++++++++++++++
-
-An attacker could send large volumes of messages to a chatroom with the victim
-making the chatroom unusable.
-
-Threat: Banning users without necessary authorisation
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-An attacker could attempt to ban a user from a chatroom with the necessary
-authorisation.
-
-Spoofing
-~~~~~~~~
-
-An attacker could try to send a message claiming to be from the victim without
-the victim having sent the message in order to:
-
-* Impersonate the victim while performing illict activity.
-* Obtain privileges of the victim.
-
-Threat: Altering Message Contents
-+++++++++++++++++++++++++++++++++
-
-An attacker could try to alter the contents of an existing message from the
-victim.
-
-Threat: Fake Message "origin" Field
-+++++++++++++++++++++++++++++++++++
-
-An attacker could try to send a new message purporting to be from the victim
-with a phony "origin" field.
-
-Spamming
-~~~~~~~~
-
-The attacker could try to send a high volume of solicicted or unsolicted
-messages to the victim in order to:
-
-* Find victims for scams.
-* Market unwanted products.
-
-Threat: Unsoliticted Messages
-+++++++++++++++++++++++++++++
-
-An attacker could try to send messages to victims who do not wish to receive
-them.
-
-Threat: Abusive Messages
-++++++++++++++++++++++++
-
-An attacker could send abusive or threatening messages to the victim
-
-Spying
-~~~~~~
-
-The attacker could try to access message contents or metadata for messages sent
-by the victim or to the victim that were not intended to reach the attacker in
-order to:
-
-* Gain sensitive personal or commercial information.
-* Impersonate the victim using credentials contained in the messages.
-  (e.g. password reset messages)
-* Discover who the victim was talking to and when.
-
-Threat: Disclosure during Transmission
-++++++++++++++++++++++++++++++++++++++
-
-An attacker could try to expose the message contents or metadata during
-transmission between the servers.
-
-Threat: Disclosure to Servers Outside Chatroom
-++++++++++++++++++++++++++++++++++++++++++++++
-
-An attacker could try to convince servers within a chatroom to send messages to
-a server it controls that was not authorised to be within the chatroom.
-
-Threat: Disclosure to Servers Within Chatroom
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-An attacker could take control of a server within a chatroom to expose message
-contents or metadata for messages in that room.
-
-Rate limiting
--------------
-Home servers SHOULD implement rate limiting to reduce the risk of being overloaded. If a
-request is refused due to rate limiting, it should return a standard error response of
-the form::
-
-  {
-    "errcode": "M_LIMIT_EXCEEDED",
-    "error": "string",
-    "retry_after_ms": integer (optional)
-  }
-
-The ``retry_after_ms`` key SHOULD be included to tell the client how long they have to wait
-in milliseconds before they can try again.
-
-.. TODO
-  - Surely we should recommend an algorithm for the rate limiting, rather than letting every
-    homeserver come up with their own idea, causing totally unpredictable performance over
-    federated rooms?
-  - crypto (s-s auth)
-  - E2E
-  - Lawful intercept + Key Escrow
-  TODO Mark
-
-Policy Servers
-==============
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  We should mention them in the Architecture section at least...
-  
-Content repository
-==================
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  - path to upload
-  - format for thumbnail paths, mention what it is protecting against.
-  - content size limit and associated M_ERROR.
-
-Address book repository
-=======================
-.. NOTE::
-  This section is a work in progress.
-
-.. TODO
-  - 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?
-
-
-Glossary
-========
-.. NOTE::
-  This section is a work in progress.
-
-Backfilling:
-  The process of synchronising historic state from one home server to another,
-  to backfill the event storage so that scrollback can be presented to the
-  client(s). Not to be confused with pagination.
-
-Context:
-  A single human-level entity of interest (currently, a chat room)
-
-EDU (Ephemeral Data Unit):
-  A message that relates directly to a given pair of home servers that are
-  exchanging it. EDUs are short-lived messages that related only to one single
-  pair of servers; they are not persisted for a long time and are not forwarded
-  on to other servers. Because of this, they have no internal ID nor previous
-  EDUs reference chain.
-
-Event:
-  A record of activity that records a single thing that happened on to a context
-  (currently, a chat room). These are the "chat messages" that Synapse makes
-  available.
-
-PDU (Persistent Data Unit):
-  A message that relates to a single context, irrespective of the server that
-  is communicating it. PDUs either encode a single Event, or a single State
-  change. A PDU is referred to by its PDU ID; the pair of its origin server
-  and local reference from that server.
-
-PDU ID:
-  The pair of PDU Origin and PDU Reference, that together globally uniquely
-  refers to a specific PDU.
-
-PDU Origin:
-  The name of the origin server that generated a given PDU. This may not be the
-  server from which it has been received, due to the way they are copied around
-  from server to server. The origin always records the original server that
-  created it.
-
-PDU Reference:
-  A local ID used to refer to a specific PDU from a given origin server. These
-  references are opaque at the protocol level, but may optionally have some
-  structured meaning within a given origin server or implementation.
-
-Presence:
-  The concept of whether a user is currently online, how available they declare
-  they are, and so on. See also: doc/model/presence
-
-Profile:
-  A set of metadata about a user, such as a display name, provided for the
-  benefit of other users. See also: doc/model/profiles
-
-Room ID:
-  An opaque string (of as-yet undecided format) that identifies a particular
-  room and used in PDUs referring to it.
-
-Room Alias:
-  A human-readable string of the form #name:some.domain that users can use as a
-  pointer to identify a room; a Directory Server will map this to its Room ID
-
-State:
-  A set of metadata maintained about a Context, which is replicated among the
-  servers in addition to the history of Events.
-
-User ID:
-  A string of the form @localpart:domain.name that identifies a user for
-  wire-protocol purposes. The localpart is meaningless outside of a particular
-  home server. This takes a human-readable form that end-users can use directly
-  if they so wish, avoiding the 3PIDs.
-
-Transaction:
-  A message which relates to the communication between a given pair of servers.
-  A transaction contains possibly-empty lists of PDUs and EDUs.
-
-.. TODO
-  This glossary contradicts the terms used above - especially on State Events v. "State"
-  and Non-State Events v. "Events".  We need better consistent names.
-
-.. Links through the external API docs are below
-.. =============================================
-
-.. |createRoom| replace:: ``/createRoom``
-.. _createRoom: /docs/api/client-server/#!/-rooms/create_room
-
-.. |initialSync| replace:: ``/initialSync``
-.. _initialSync: /docs/api/client-server/#!/-events/initial_sync
-
-.. |/rooms/<room_id>/initialSync| replace:: ``/rooms/<room_id>/initialSync``
-.. _/rooms/<room_id>/initialSync: /docs/api/client-server/#!/-rooms/get_room_sync_data
-
-.. |login| replace:: ``/login``
-.. _login: /docs/api/client-server/#!/-login
-
-.. |register| replace:: ``/register``
-.. _register: /docs/api/client-server/#!/-registration
-
-.. |/rooms/<room_id>/messages| replace:: ``/rooms/<room_id>/messages``
-.. _/rooms/<room_id>/messages: /docs/api/client-server/#!/-rooms/get_messages
-
-.. |/rooms/<room_id>/members| replace:: ``/rooms/<room_id>/members``
-.. _/rooms/<room_id>/members: /docs/api/client-server/#!/-rooms/get_members
-
-.. |/rooms/<room_id>/state| replace:: ``/rooms/<room_id>/state``
-.. _/rooms/<room_id>/state: /docs/api/client-server/#!/-rooms/get_state_events
-
-.. |/rooms/<room_id>/send/<event_type>| replace:: ``/rooms/<room_id>/send/<event_type>``
-.. _/rooms/<room_id>/send/<event_type>: /docs/api/client-server/#!/-rooms/send_non_state_event
-
-.. |/rooms/<room_id>/state/<event_type>/<state_key>| replace:: ``/rooms/<room_id>/state/<event_type>/<state_key>``
-.. _/rooms/<room_id>/state/<event_type>/<state_key>: /docs/api/client-server/#!/-rooms/send_state_event
-
-.. |/rooms/<room_id>/invite| replace:: ``/rooms/<room_id>/invite``
-.. _/rooms/<room_id>/invite: /docs/api/client-server/#!/-rooms/invite
-
-.. |/rooms/<room_id>/join| replace:: ``/rooms/<room_id>/join``
-.. _/rooms/<room_id>/join: /docs/api/client-server/#!/-rooms/join_room
-
-.. |/rooms/<room_id>/leave| replace:: ``/rooms/<room_id>/leave``
-.. _/rooms/<room_id>/leave: /docs/api/client-server/#!/-rooms/leave
-
-.. |/rooms/<room_id>/ban| replace:: ``/rooms/<room_id>/ban``
-.. _/rooms/<room_id>/ban: /docs/api/client-server/#!/-rooms/ban
-
-.. |/join/<room_alias_or_id>| replace:: ``/join/<room_alias_or_id>``
-.. _/join/<room_alias_or_id>: /docs/api/client-server/#!/-rooms/join
-
-.. _`Event Stream`: /docs/api/client-server/#!/-events/get_event_stream
-