3.1.1   Example

At a high level, the requests made for an API call completing an auth flow with three stages will resemble the following diagram:

 _______________________
|       Stage 1         |
| type: "<stage type1>" |
|  ___________________  |
| |_Request_1_________| | <-- Returns "session" key which is used throughout.
|  ___________________  |
| |_Request_2_________| |
|_______________________|
          |
          |
 _________V_____________
|       Stage 2         |
| type: "<stage type2>" |
|  ___________________  |
| |_Request_1_________| |
|  ___________________  |
| |_Request_2_________| |
|  ___________________  |
| |_Request_3_________| |
|_______________________|
          |
          |
 _________V_____________
|       Stage 3         |
| type: "<stage type3>" |
|  ___________________  |
| |_Request_1_________| | <-- Returns API response
|_______________________|

This specification defines the following login types:

• m.login.password
• m.login.recaptcha
• m.login.oauth2
• m.login.email.identity
• m.login.token
• m.login.dummy

3.1.2   Password-based

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.password",
  "user": "<user_id or user localpart>",
  "password": "<password>"
}

3.1.3   Google ReCaptcha

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.recaptcha",
  "response": "<captcha response>"
}

3.1.4   Token-based

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.token",
  "user": "<user_id or user localpart>",
  "token": "<token>",
  "txn_id": "<client generated nonce>"
}

The nonce should be a random string generated by the client for the request. The same nonce should be used if retrying the request.

There are many ways a client may receive a token, including via an email or from an existing logged in device.

The txn_id may be used by the server to disallow other devices from using the token, thus providing "single use" tokens while still allowing the device to retry the request. This would be done by tying the token to the txn_id server side, as well as potentially invalidating the token completely once the device has successfully logged in (e.g. when we receive a request from the newly provisioned access_token).

The token must be a macaroon.

3.1.5   OAuth2-based

The homeserver acts as a 'confidential' client for the purposes of OAuth2. If the uri is a service 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 one service which the homeserver 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' redirects to the redirect URI with the auth code. Homeservers can choose any path for the redirect URI. Once the OAuth flow has completed, the client retries the request with the session only, as above.

3.1.6   Email-based (identity server)

Prior to submitting this, the client should authenticate with an identity server. After authenticating, the session information should be submitted to the homeserver.

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.email.identity",
  "threepidCreds": [
    {
      "sid": "<identity server session id>",
      "client_secret": "<identity server client secret>",
      "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
    }
  ]
}

3.1.7   Dummy Auth

To respond to this type, reply with an auth dict with just the type and session, if provided:

{
  "type": "m.login.dummy",
}

3.1.8   Fallback

Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login type, it can direct the user to a web browser with the URL of a fallback page which will allow the user to complete that login step out-of-band in their web browser. The URL it should open is:

/_matrix/client/r0/auth/<stage type>/fallback/web?session=<session ID>

Where stage type is the type name of the stage it is attempting and session id is the ID of the session given by the homeserver.

This MUST return an HTML page which can perform this authentication stage. This page must attempt to call the JavaScript function window.onAuthDone when the authentication has been completed.

3.2.1   POST /_matrix/client/r0/register

Register for an account on this homeserver.

There are two kinds of user account:

• user accounts. These accounts may use the full API described in this specification.
• guest accounts. These accounts may have limited permissions and may not be supported by all servers.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/register?kind=guest HTTP/1.1
Content-Type: application/json

{
  "username": "cheeky_monkey",
  "password": "ilovebananas",
  "bind_email": false
}

Responses:

Status code 200:

The account has been registered.

Example

{
  "user_id": "@cheeky_monkey:matrix.org",
  "access_token": "abc123",
  "home_server": "matrix.org",
  "refresh_token": "def456"
}

Status code 400:

Part of the request was invalid. This may include one of the following error codes:

• M_USER_IN_USE : The desired user ID is already taken.
• M_EXCLUSIVE : The desired user ID is in the exclusive namespace claimed by an application service.

These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered whilst the client was performing authentication.

Homeservers MUST perform the relevant checks and return these codes before performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication.

Example

{
    "errcode": "M_USER_IN_USE",
    "error": "Desired user ID is already taken."
}

3.2.2   POST /_matrix/client/r0/login

Authenticates the user by password, and issues an access token they can use to authorize themself in subsequent requests.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/login HTTP/1.1
Content-Type: application/json

{
  "type": "m.login.pasword",
  "user": "cheeky_monkey",
  "password": "ilovebananas"
}

Responses:

Status code 200:

The user has been authenticated.

Example

{
  "user_id": "@cheeky_monkey:matrix.org",
  "access_token": "abc123",
  "home_server": "matrix.org"
}

Status code 400:

Part of the request was invalid. For example, the login type may not be recognised.

Example

{
    "errcode": "M_UNKNOWN",
    "error": "Bad login type."
}

Status code 403:

The login attempt failed. For example, the password may have been incorrect.

Example

{"errcode": "M_FORBIDDEN"}

3.2.3   POST /_matrix/client/r0/tokenrefresh

Exchanges a refresh token for a new access token. This is intended to be used if the access token has expired.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/tokenrefresh HTTP/1.1
Content-Type: application/json

{
  "refresh_token": "a1b2c3"
}

Responses:

Status code 200:

The refresh token was accepted, and a new access token has been issued. The passed refresh token is no longer valid and cannot be used. A new refresh token will have been returned unless some policy does not allow the user to continue to renew their session.

Example

{
  "access_token": "bearwithme123",
  "refresh_token": "exchangewithme987"
}

Status code 403:

The exchange attempt failed. For example, the refresh token may have already been used.

Example

{"errcode": "M_FORBIDDEN"}

3.2.4   Login Fallback

If a client does not recognize any or all login flows it can use the fallback login API:

GET /_matrix/static/client/login/

This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function window.onLogin when login has been successfully completed.

3.2.5   Changing Password

Request:

POST /_matrix/client/r0/account/password

This API endpoint uses the User-Interactive Authentication API. An access token should be submitted to this endpoint if the client has an active session. The homeserver may change the flows available depending on whether a valid access token is provided.

The body of the POST request is a JSON object containing:

new_password

The new password for the account.

On success, an empty JSON object is returned.

The error code M_NOT_FOUND is returned if the user authenticated with a third party identifier but the homeserver could not find a matching account in its database.

3.2.6   Adding Account Administrative Contact Information

A homeserver may keep some contact information for administrative use. This is independent of any information kept by any Identity Servers.

POST /_matrix/client/r0/account/3pid HTTP/1.1
Content-Type: application/json

{
  "threePidCreds": {
    "id_server": "matrix.org",
    "sid": "abc123987",
    "client_secret": "d0n'tT3ll"
  },
  "bind": false
}

{}

{
  "errcode": "M_THREEPID_AUTH_FAILED",
  "error": "The third party credentials could not be verified by the identity server."
}

GET /_matrix/client/r0/account/3pid HTTP/1.1

{
  "threepids": [
    {
      "medium": "email",
      "address": "monkey@banana.island"
    }
  ]
}

POST /_matrix/client/r0/account/password HTTP/1.1
Content-Type: application/json

{
  "new_password": "ihatebananas"
}

{}

6.2.1   GET /_matrix/client/r0/events

This will listen for new events and return them to the caller. This will block until an event is received, or until the timeout is reached.

Request format:

Response format:

Event

UnsignedData

Example request:

GET /_matrix/client/r0/events?from=s3456_9_0&timeout=35000 HTTP/1.1

Response:

Status code 200:

The events received, which may be none.

Example

{
  "start": "s3456_9_0",
  "end": "s3457_9_0",
  "chunk": [
    {
      "age": 32,
      "content": {
          "body": "incoming message",
          "msgtype": "m.text"
      },
      "event_id": "$14328055551tzaee:localhost",
      "origin_server_ts": 1432804485886,
      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
      "type": "m.room.message",
      "sender": "@bob:localhost"
    }
  ]
}

6.2.2   GET /_matrix/client/r0/events/{eventId}

Get a single event based on event_id. You must have permission to retrieve this event e.g. by being a member in the room for this event.

Request format:

Example request:

GET /_matrix/client/r0/events/%24asfDuShaf7Gafaw%3Amatrix.org HTTP/1.1

Response:

Status code 200:

The full event.

Example

{
  "content": {
    "body": "Hello world!",
    "msgtype": "m.text"
  },
  "room_id:": "!wfgy43Sg4a:matrix.org",
  "sender": "@bob:matrix.org",
  "event_id": "$asfDuShaf7Gafaw:matrix.org",
  "type": "m.room.message"
}

6.2.3   GET /_matrix/client/r0/initialSync

This returns the full state for this user, with an optional limit on the number of messages per room to return.

Request format:

Response format:

RoomInfo

Event

InviteEvent

EventContent

Invite

signed

StrippedState

PaginationChunk

RoomEvent

StateEvent

UnsignedData

Example request:

GET /_matrix/client/r0/initialSync?limit=2&archived=true HTTP/1.1

Response:

Status code 200:

The user's current state.

Example

{
    "end": "s3456_9_0",
    "presence": [
        {
            "content": {
                "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                "displayname": "Bob",
                "last_active_ago": 31053,
                "presence": "online",
                "user_id": "@bob:localhost"
            },
            "type": "m.presence"
        }
    ],
    "account_data": [
      {
        "type": "org.example.custom.config",
        "content": {
          "custom_config_key": "custom_config_value"
        }
      }
    ],
    "rooms": [
        {
            "membership": "join",
            "messages": {
                "chunk": [
                    {
                        "age": 343513403,
                        "content": {
                            "body": "foo",
                            "msgtype": "m.text"
                        },
                        "event_id": "$14328044851tzTJS:localhost",
                        "origin_server_ts": 1432804485886,
                        "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                        "type": "m.room.message",
                        "sender": "@alice:localhost"
                    },
                    {
                        "age": 343511809,
                        "content": {
                            "body": "bar",
                            "msgtype": "m.text"
                        },
                        "event_id": "$14328044872spjFg:localhost",
                        "origin_server_ts": 1432804487480,
                        "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                        "type": "m.room.message",
                        "sender": "@bob:localhost"
                    }
                ],
                "end": "s3456_9_0",
                "start": "t44-3453_9_0"
            },
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "state": [
                {
                    "age": 7148266897,
                    "content": {
                        "join_rule": "public"
                    },
                    "event_id": "$14259997323TLwtb:localhost",
                    "origin_server_ts": 1425999732392,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.join_rules",
                    "sender": "@alice:localhost"
                },
                {
                    "age": 6547561012,
                    "content": {
                        "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
                        "membership": "join"
                    },
                    "event_id": "$1426600438280zExKY:localhost",
                    "membership": "join",
                    "origin_server_ts": 1426600438277,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "@alice:localhost",
                    "type": "m.room.member",
                    "sender": "@alice:localhost"
                },
                {
                    "age": 7148267200,
                    "content": {
                        "creator": "@alice:localhost"
                    },
                    "event_id": "$14259997320KhbwJ:localhost",
                    "origin_server_ts": 1425999732089,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.create",
                    "sender": "@alice:localhost"
                },
                {
                    "age": 1622568720,
                    "content": {
                        "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                        "displayname": "Bob",
                        "membership": "join"
                    },
                    "event_id": "$1431525430134MxlLX:localhost",
                    "origin_server_ts": 1431525430569,
                    "replaces_state": "$142652023736BSXcM:localhost",
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "@bob:localhost",
                    "type": "m.room.member",
                    "sender": "@bob:localhost"
                },
                {
                    "age": 7148267004,
                    "content": {
                        "ban": 50,
                        "events": {
                            "m.room.name": 100,
                            "m.room.power_levels": 100
                        },
                        "events_default": 0,
                        "kick": 50,
                        "redact": 50,
                        "state_default": 50,
                        "users": {
                            "@alice:localhost": 100
                        },
                        "users_default": 0
                    },
                    "event_id": "$14259997322mqfaq:localhost",
                    "origin_server_ts": 1425999732285,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.power_levels",
                    "sender": "@alice:localhost"
                }
            ],
            "visibility": "private",
            "account_data": [
              {
                "type": "m.tag",
                "content": {"tags": {"work": {"order": 1}}}
              },
              {
                "type": "org.example.custom.room.config",
                "content": {
                  "custom_config_key": "custom_config_value"
                }
              }
            ]
        }
    ]
}

6.2.4   GET /_matrix/client/r0/sync

Synchronise the client's state with the latest state on the server. Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages.

Request format:

Response format:

Presence

Rooms

Invited Room

InviteState

Joined Room

Account Data

Ephemeral

Left Room

State

Timeline

Event

Unsigned

Example request:

GET /_matrix/client/r0/sync?filter=66696p746572&since=s72594_4483_1934&full_state=false&set_presence=offline&timeout=30000 HTTP/1.1

Response:

Status code 200:

The initial snapshot or delta for the client to use to update their state.

Example

{
  "next_batch": "s72595_4483_1934",
  "presence": {
    "events": [
      {
        "sender": "@alice:example.com",
        "type": "m.presence",
        "content": {"presence": "online"}
      }
    ]
  },
  "account_data": {
    "events": [
      {
        "type": "org.example.custom.config",
        "content": {
          "custom_config_key": "custom_config_value"
        }
      }
    ]
  },
  "rooms": {
    "join": {
      "!726s6s6q:example.com": {
        "state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@alice:example.com",
              "content": {"membership": "join"},
              "origin_server_ts": 1417731086795,
              "event_id": "$66697273743031:example.com"
            }
          ]
        },
        "timeline": {
          "events": [
            {
              "sender": "@bob:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {"membership": "join"},
              "prev_content": {"membership": "invite"},
              "origin_server_ts": 1417731086795,
              "event_id": "$7365636s6r6432:example.com"
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.message",
              "age": 124524,
              "txn_id": "1234",
              "content": {
                "body": "I am a fish",
                "msgtype": "m.text"
              },
              "origin_server_ts": 1417731086797,
              "event_id": "$74686972643033:example.com"
            }
          ],
          "limited": true,
          "prev_batch": "t34-23535_0_0"
        },
        "ephemeral": {
          "events": [
            {
              "type": "m.typing",
              "content": {"user_ids": ["@alice:example.com"]}
            }
          ]
        },
        "account_data": {
          "events": [
            {
              "type": "m.tag",
              "content": {"tags": {"work": {"order": 1}}}
            },
            {
              "type": "org.example.custom.room.config",
              "content": {
                "custom_config_key": "custom_config_value"
              }
            }
          ]
        }
      }
    },
    "invite": {
      "!696r7674:example.com": {
        "invite_state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.name",
              "state_key": "",
              "content": {"name": "My Room Name"}
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {"membership": "invite"}
            }
          ]
        }
      }
    },
    "leave": {}
  }
}

6.3.1   GET /_matrix/client/r0/rooms/{roomId}/initialSync

Get a copy of the current state and the most recent messages in a room.

Request format:

Response format:

RoomInfo

Event

PaginationChunk

RoomEvent

StateEvent

UnsignedData

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/initialSync HTTP/1.1

Response:

Status code 200:

The current state of the room

Example

{
  "membership": "join",
  "messages": {
    "chunk": [
      {
        "age": 343513403,
        "content": {
          "body": "foo",
          "msgtype": "m.text"
        },
        "event_id": "$14328044851tzTJS:example.com",
        "origin_server_ts": 1432804485886,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "sender": "@alice:example.com"
      },
      {
        "age": 343511809,
        "content": {
          "body": "bar",
          "msgtype": "m.text"
        },
        "event_id": "$14328044872spjFg:example.com",
        "origin_server_ts": 1432804487480,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "sender": "@bob:example.com"
      }
    ],
    "end": "s3456_9_0",
    "start": "t44-3453_9_0"
  },
  "room_id": "!636q39766251:example.com",
  "state": [
    {
      "age": 7148266897,
      "content": {
        "join_rule": "public"
      },
      "event_id": "$14259997323TLwtb:example.com",
      "origin_server_ts": 1425999732392,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.join_rules",
      "sender": "@alice:example.com"
    },
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "sender": "@alice:example.com"
    },
    {
      "age": 7148267200,
      "content": {
          "creator": "@alice:example.com"
      },
      "event_id": "$14259997320KhbwJ:example.com",
      "origin_server_ts": 1425999732089,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.create",
      "sender": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "sender": "@bob:example.com"
    },
    {
      "age": 7148267004,
      "content": {
        "ban": 50,
        "events": {
          "m.room.name": 100,
          "m.room.power_levels": 100
        },
        "events_default": 0,
        "kick": 50,
        "redact": 50,
        "state_default": 50,
        "users": {
          "@alice:example.com": 100
        },
        "users_default": 0
      },
      "event_id": "$14259997322mqfaq:example.com",
      "origin_server_ts": 1425999732285,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.power_levels",
      "sender": "@alice:example.com"
    }
  ],
  "visibility": "private",
  "account_data": [{
      "type": "m.tag",
      "content": {"tags": {"work": {"order": "1"}}}
  }]
}

6.3.2   GET /_matrix/client/r0/rooms/{roomId}/members

Get the list of members for this room.

Request format:

Response format:

MemberEvent

EventContent

Invite

signed

StrippedState

UnsignedData

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/members HTTP/1.1

Response:

Status code 200:

A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left te room then this will be the members of the room when you left.

Example

{
  "chunk": [
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "sender": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "sender": "@bob:example.com"
    }
  ]
}

6.3.3   GET /_matrix/client/r0/rooms/{roomId}/state

Get the state events for the current state of a room.

Request format:

Response format:

RoomState

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state HTTP/1.1

Response:

Status code 200:

The current state of the room

Example

[
  {
      "age": 7148266897,
      "content": {
          "join_rule": "public"
      },
      "event_id": "$14259997323TLwtb:example.com",
      "origin_server_ts": 1425999732392,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.join_rules",
      "sender": "@alice:example.com"
  },
  {
      "age": 6547561012,
      "content": {
          "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
          "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "sender": "@alice:example.com"
  },
  {
      "age": 7148267200,
      "content": {
          "creator": "@alice:example.com"
      },
      "event_id": "$14259997320KhbwJ:example.com",
      "origin_server_ts": 1425999732089,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.create",
      "sender": "@alice:example.com"
  },
  {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "sender": "@bob:example.com"
  },
  {
      "age": 7148267004,
      "content": {
          "ban": 50,
          "events": {
              "m.room.name": 100,
              "m.room.power_levels": 100
           },
           "events_default": 0,
           "kick": 50,
           "redact": 50,
           "state_default": 50,
           "users": {
               "@alice:example.com": 100
           },
           "users_default": 0
      },
      "event_id": "$14259997322mqfaq:example.com",
      "origin_server_ts": 1425999732285,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.power_levels",
      "sender": "@alice:example.com"
  }
]

6.3.4   GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

This looks up the state event with the empty state key.

Request format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name HTTP/1.1

Response:

Status code 200:

The content of the state event.

Example

{"name": "Example room name"}

6.3.5   GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

Request format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1

Response:

Status code 200:

The content of the state event.

Example

{"name": "Example room name"}

6.3.6   GET /_matrix/client/r0/rooms/{roomId}/messages

This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room.

Request format:

Response format:

Example request:

GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/messages?from=s345_678_333&dir=b&limit=3 HTTP/1.1

Response:

Status code 200:

A list of messages with a new token to request more.

Example

{
  "start": "t47429-4392820_219380_26003_2265",
  "end": "t47409-4357353_219380_26003_2265",
  "chunk": [
    {
      "origin_server_ts": 1444812213737,
      "user_id": "@alice:example.com",
      "event_id": "$1444812213350496Caaaa:example.com",
      "content": {
        "body": "hello world",
        "msgtype":"m.text"
      },
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.message",
      "age": 1042
    },
    {
      "origin_server_ts": 1444812194656 ,
      "user_id": "@bob:example.com",
      "event_id": "$1444812213350496Cbbbb:example.com",
      "content": {
        "body": "the world is big",
        "msgtype":"m.text"
      },
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.message",
      "age": 20123
    },
    {
      "origin_server_ts": 1444812163990,
      "user_id": "@bob:example.com",
      "event_id": "$1444812213350496Ccccc:example.com",
      "content": {
        "name": "New room name"
      },
      "prev_content": {
        "name": "Old room name"
      },
      "state_key": "",
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.name",
      "age": 50789
    }
  ]
}

6.4.1   PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}

State events can be sent using this endpoint. These events will be overwritten if <room id>, <event type> and <state key> all match. This endpoint forces the state key to be the empty string.

Requests to this endpoint cannot use transaction IDs like other PUT paths because they cannot be differentiated from the state_key. Furthermore, POST is unsupported on state paths.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Request format:

Response format:

Example request:

PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name HTTP/1.1
Content-Type: application/json

{
    "name": "New name for the room"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

6.4.2   PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}

State events can be sent using this endpoint. This endpoint is equivalent to calling /rooms/{roomId}/state/{eventType}/{stateKey} with an empty stateKey. Previous state events with matching <roomId> and <eventType>, and empty <stateKey>, will be overwritten.

Requests to this endpoint cannot use transaction IDs like other PUT paths because they cannot be differentiated from the state_key. Furthermore, POST is unsupported on state paths.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Request format:

Response format:

Example request:

PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1
Content-Type: application/json

{
    "name": "New name for the room"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

Examples

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" }

6.4.3   PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}

This endpoint is used to send a message event to a room. Message events allow access to historical events and pagination, making them suited for "once-off" activity in a room.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Request format:

Response format:

Example request:

PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/send/m.room.message/35 HTTP/1.1
Content-Type: application/json

{
  "msgtype": "m.text",
  "body": "hello"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

6.5.1   Events

{
    "age": 242352,
    "content": {
        "reason": "Spamming"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "redacts": "!fukweghifu23:localhost",
    "room_id": "!Cuyf34gef24t:localhost",
    "sender": "@example:localhost",
    "type": "m.room.redaction"
}

6.5.2   Client behaviour

PUT /_matrix/client/api/r0/rooms/%21637q39766251%3Aexample.com/redact/bai2b1i9%3Amatrix.org/37 HTTP/1.1
Content-Type: application/json

{
  "reason": "Indecent material"
}

{
    "event_id": "YUwQidLecu"
}

7.1.1   POST /_matrix/client/r0/createRoom

Create a new room with various configuration options.

Request format:

Response format:

Example request:

POST /_matrix/client/r0/createRoom HTTP/1.1
Content-Type: application/json

{
  "preset": "public_chat",
  "room_alias_name": "thepub",
  "name": "The Grand Duke Pub",
  "topic": "All about happy hour",
  "creation_content": {
      "m.federate": false
  }
}

Response:

Status code 200:

Information about the newly created room.

Example

{
  "room_id": "!sefiuhWgwghwWgh:example.com"
}

7.2.1   PUT /_matrix/client/r0/directory/room/{roomAlias}

Create a new mapping from room alias to room ID.

Request format:

Example request:

PUT /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1
Content-Type: application/json

{
  "room_id": "!abnjk1jdasj98:capuchins.com"
}

Response:

Status code 200:

The mapping was created.

Example

{}

7.2.2   DELETE /_matrix/client/r0/directory/room/{roomAlias}

Remove a mapping of room alias to room ID.

Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.

Request format:

Example request:

DELETE /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1

Response:

Status code 200:

The mapping was deleted.

Example

{}

7.2.3   GET /_matrix/client/r0/directory/room/{roomAlias}

Get the room ID corresponding to this room alias.

Request format:

Response format:

Example request:

GET /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1

Responses:

Status code 200:

The room ID and other information for this alias.

Example

{
  "room_id": "!abnjk1jdasj98:capuchins.com",
  "servers": [
    "capuchins.com",
    "matrix.org",
    "another.com"
  ]
}

Status code 409:

A room alias with that name already exists.

Example

{
  "errcode": "M_UNKNOWN",
  "error": "Room alias #monkeys:matrix.org already exists."
}

Status code 404:

There is no mapped room ID for this room alias.

Example

{
  "errcode": "M_NOT_FOUND",
  "error": "Room ID !abnjk1jdasj98:capuchins.com not found."
}

7.4.1   POST /_matrix/client/r0/rooms/{roomId}/invite

Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter knows the Matrix identifier of the invitee. The other is documented in the third party invites section.

This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the room.

Only users currently in a particular room can invite other users to join that room.

If the user was invited to the room, the homeserver will append a m.room.member event to the room.

Request format:

Example request:

POST /_matrix/client/r0/rooms/%21d41d8cd%3Amatrix.org/invite  HTTP/1.1
Content-Type: application/json

{
  "user_id": "@cheeky_monkey:matrix.org"
}

Responses:

Status code 200:

The user has been invited to join the room.

Example

{}

Status code 403:

You do not have permission to invite the user to the room. A meaningful errcode and description error text will be returned. Example reasons for rejections are:

• The invitee has been banned from the room.
• The invitee is already a member of the room.
• The inviter is not currently in the room.
• The inviter's power level is insufficient to invite users to the room.

Example

{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}

7.4.2   POST /_matrix/client/r0/join/{roomId}

/_matrix/client/r0/join/{roomId} is an alias for /_matrix/client/r0/rooms/{roomId}/join.

7.4.3   POST /_matrix/client/r0/rooms/{roomId}/join

This API starts a user participating in a particular room, if that user is allowed to participate in that room. After this call, the client is allowed to see all current state events in the room, and all subsequent events associated with the room until the user leaves the room.

After a user has joined a room, the room will appear as an entry in the response of the /initialSync API.

Request format:

Example request:

POST /_matrix/client/r0/rooms/%23monkeys%3Amatrix.org/join HTTP/1.1

Responses:

Status code 200:

The room has been joined.

The joined room ID must be returned in the room_id field.

Example

{"room_id": "!d41d8cd:matrix.org"}

Status code 403:

You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are:

• The room is invite-only and the user was not invited.
• The user has been banned from the room.

Example

{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}

7.4.4   POST /_matrix/client/r0/rooms/{roomId}/ban

Ban a user in the room. If the user is currently in the room, also kick them.

When a user is banned from a room, they may not join it until they are unbanned.

The caller must have the required power level in order to perform this operation.

Request format:

Example request:

POST /_matrix/client/r0/rooms/%21e42d8c%3Amatrix.org/ban HTTP/1.1
Content-Type: application/json

{
  "reason": "Telling unfunny jokes",
  "user_id": "@cheeky_monkey:matrix.org"
}

Responses:

Status code 200:

The user has been kicked and banned from the room.

Example

{}

Status code 403:

You do not have permission to ban the user from the room. A meaningful errcode and description error text will be returned. Example reasons for rejections are:

• The banner is not currently in the room.
• The banner's power level is insufficient to ban users from the room.

Example

{
  "errcode": "M_FORBIDDEN",
  "error": "You do not have a high enough power level to ban from this room."
}

7.5.1   POST /_matrix/client/r0/rooms/{roomId}/forget

This API stops a user remembering about a particular room.

In general, history is a first class citizen in Matrix. After this API is called, however, a user will no longer be able to retrieve history for this room. If all users on a homeserver forget a room, the room is eligible for deletion from that homeserver.

If the user is currently joined to the room, they will implicitly leave the room as part of this API call.

Request format:

Example request:

POST /_matrix/client/r0/rooms/%21au1ba7o%3Amatrix.org/forget HTTP/1.1

Response:

Status code 200:

The room has been forgotten.

Example

{}

7.5.2   POST /_matrix/client/r0/rooms/{roomId}/leave

This API stops a user participating in a particular room.

If the user was already in the room, they will no longer be able to see new events in the room. If the room requires an invite to join, they will need to be re-invited before they can re-join.

If the user was invited to the room, but had not joined, this call serves to reject the invite.

The user will still be allowed to retrieve history from the room which they were previously allowed to see.

Request format:

Example request:

POST /_matrix/client/r0/rooms/%21nkl290a%3Amatrix.org/leave HTTP/1.1

Response:

Status code 200:

The room has been left.

Example

{}

7.7.1   GET /_matrix/client/r0/publicRooms

Lists the public rooms on the server.

This API returns paginated responses.

Request format:

No parameters

Response format:

PublicRoomsChunk

Example request:

GET /_matrix/client/r0/publicRooms HTTP/1.1

Response:

Status code 200:

A list of the rooms on the server.

Example

{
  "chunk": [
    {
      "aliases": ["#murrays:cheese.bar"],
      "guest_can_join": false,
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "start": "p190q",
  "end": "p1902"
}

10.5.1   m.room.aliases

State Event

state_key: The homeserver domain which owns these room aliases.

This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The state_key for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the m.room.aliases events, one for each homeserver. Clients should check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.

Example:

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

10.5.2   m.room.canonical_alias

State Event

state_key: A zero-length string.

This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.

Example:

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

10.5.3   m.room.create

State Event

state_key: A zero-length string.

This is the first event in a room and cannot be changed. It acts as the root of all other events.

Example:

{
    "age": 242352,
    "content": {
        "creator": "@example:localhost"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "sender": "@example:localhost",
    "state_key": "",
    "type": "m.room.create"
}

10.5.4   m.room.join_rules

State Event

state_key: A zero-length string.

A room may be public meaning anyone can join the room without any prior action. Alternatively, it can be invite meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, knock and private are reserved keywords which are not implemented.

Example:

{
    "age": 242352,
    "content": {
        "join_rule": "public"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "sender": "@example:localhost",
    "state_key": "",
    "type": "m.room.join_rules"
}

10.5.5   m.room.member

State Event

state_key: The user_id this membership event relates to.

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.

The third_party_invite property will be set if this invite is an invite event and is the successor of an m.room.third_party_invite event, and absent otherwise.

This event may also include an invite_room_state key outside the content key. If present, this contains an array of StrippedState Events. These events provide information on a few select state events such as the room name. EventContent