specification.rst

                  How data flows between clients
                  ==============================

{ Matrix client A }                             { Matrix client B }
    ^          |                                    ^          |
    |  events  |                                    |  events  |
    |          V                                    |          V
+------------------+                            +------------------+
|                  |---------( HTTP )---------->|                  |
|   Home Server    |                            |   Home Server    |
|                  |<--------( HTTP )-----------|                  |
+------------------+        Federation          +------------------+
@localpart:domain
!opaque_id:domain
 { @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              |
                 |.................................|
#room_alias:domain

.. TODO
    - Need to specify precise grammar for Room IDs
       GET
#matrix:domain.com      !aaabaa:matrix.org
        |                    ^
        |                    |
 _______V____________________|____
|          domain.com            |
| Mappings:                      |
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|
{
  "errcode": "<error code>",
  "error": "<error message>"
}
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."
}
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."
}
{
  "visibility": "public",
  "room_alias_name": "the pub",
  "name": "The Grand Duke Pub",
  "topic": "All about happy hour"
}
{}
{
  "room_id": "!roomid:domain"
}
{
  "membership": "join"
}
{
  "user_id": "<user id to invite>"
}
{
  "membership": "invite"
}
{}
{
  "membership": "leave"
}
{
  "user_id": "<user id to ban"
  "reason": "string: <reason for the ban>"
}
{
  "membership": "ban"
}
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" }
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" }
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" }
PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Adomain.com
{ "animal" : "cat", "reason": "fluffy" }
PUT /rooms/!roomid:domain/state/m.room.bgd.color
{ "color": "red", "hex": "#ff0000" }
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!" }
{
  "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)",
}
{
  "mimetype" : "string (e.g. audio/aac)",
  "size" : integer (size of audio in bytes),
  "duration" : integer (duration of audio in milliseconds),
}
{
  "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)
}
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>"
    }
  ]
}
{
  "user_id": "@user:matrix.org",
  "access_token": "abcdef0123456789"
}
{
  "session": "<session id>"
}
{
  "type": "m.login.password",
  "user": "<user_id or user localpart>",
  "password": "<password>"
}
{
  "type": "m.login.oauth2",
  "user": "<user_id or user localpart>"
}
{
  "uri": <Authorization Request URI OR service selection URI>
}
{
  "uri": "https://accounts.google.com/o/oauth2/auth?response_type=code&
  client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
}
{
  "user_id": "@user:matrix.org",
  "access_token": "0123456789abcdef"
}
{
  "type": "m.login.email.code",
  "user": "<user_id or user localpart>",
  "email": "<email address>"
}
{
  "type": "m.login.email.code",
  "session": "<session id>"
}
{
  "type": "m.login.email.code",
  "session": "<session id>",
  "code": "<code in email sent>"
}
{
  "type": "m.login.email.url",
  "user": "<user_id or user localpart>",
  "email": "<email address>"
}
{
  "type": "m.login.email.url",
  "session": "<session id>"
}
{
  "type": "m.login.email.url",
  "session": "<session id>"
}
{
  "next": "<next login type>"
}
{
  "type": "<1st login type>",
  "stages": [ <1st login type>, <2nd login type>, ... , <Nth login type> ]
}
 _______________________
|    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
|_______________________|
GET matrix/client/api/v1/login/fallback
{
 "transaction_id":"916d630ea616342b42e98a3be0b74113",
 "ts":1404835423000,
 "origin":"red",
 "destination":"blue",
 "prev_ids":["e1da392e61898be4d2009b9fecce5325"],
 "pdus":[...],
 "edus":[...]
}
{
 "pdu_id":"a4ecee13e2accdadf56c1025af232176",
 "context":"#example.green",
 "origin":"green",
 "ts":1404838188000,
 "pdu_type":"m.text",
 "prev_pdus":[["blue","99d16afbc857975916f1d73e49e52b65"]],
 "content":...
 "is_state":false
}
{...,
 "is_state":true,
 "state_key":TODO
 "power_level":TODO
 "prev_state_id":TODO
 "prev_state_origin":TODO}
{"edu_type":"m.presence",
 "origin":"blue",
 "destination":"orange",
 "content":...}
{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "string",
  "retry_after_ms": integer (optional)
}