matrix
/
matrix-admin-tool
mirror of https://gitlab.com/MaSven/matrix-admin-tool.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
matrix-admin-tool/api-docs.json

12688 lines
822 KiB
JSON
Raw Permalink Blame History

{
"basePath": "/",
"consumes": [
"application/json"
],
"host": "matrix.org:8448",
"info": {
"title": "Matrix Client-Server API",
"version": "r0.3.0"
},
"paths": {
"/_matrix/client/r0/account/3pid": {
"get": {
"description": "Gets a list of the third party identifiers that the homeserver has\nassociated with the user's account.\n\nThis is *not* the same as the list of third party identifiers bound to\nthe user's Matrix ID in Identity Servers.\n\nIdentifiers in this list may be used by the homeserver as, for example,\nidentifiers that it will accept to reset the user's account password.",
"operationId": "getAccount3PIDs",
"responses": {
"200": {
"description": "The lookup was successful.",
"examples": {
"application/json": {
"threepids": [
{
"address": "monkey@banana.island",
"medium": "email"
}
]
}
},
"schema": {
"properties": {
"threepids": {
"items": {
"properties": {
"address": {
"description": "The third party identifier address.",
"type": "string"
},
"medium": {
"description": "The medium of the third party identifier.",
"enum": [
"email"
],
"type": "string"
}
},
"title": "Third party identifier",
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets a list of a user's third party identifiers.",
"tags": [
"User data"
]
},
"post": {
"description": "Adds contact information to the user's account.",
"operationId": "post3PIDs",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"example": {
"bind": false,
"three_pid_creds": {
"client_secret": "d0n'tT3ll",
"id_server": "matrix.org",
"sid": "abc123987"
}
},
"properties": {
"bind": {
"description": "Whether the homeserver should also bind this third party\nidentifier to the account's Matrix ID with the passed identity\nserver. Default: ``false``.",
"type": "boolean",
"x-example": true
},
"three_pid_creds": {
"description": "The third party credentials to associate with the account.",
"properties": {
"client_secret": {
"description": "The client secret used in the session with the Identity Server.",
"type": "string"
},
"id_server": {
"description": "The Identity Server to use.",
"type": "string"
},
"sid": {
"description": "The session identifier given by the Identity Server.",
"type": "string"
}
},
"required": [
"client_secret",
"id_server",
"sid"
],
"title": "ThreePidCredentials",
"type": "object"
}
},
"required": [
"three_pid_creds"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The addition was successful.",
"examples": {
"application/json": {},
"schema": {
"type": "object"
}
}
},
"403": {
"description": "The credentials could not be verified with the identity server.",
"examples": {
"application/json": {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Adds contact information to the user's account.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/account/deactivate": {
"post": {
"description": "Deactivate the user's account, removing all ability for the user to\nlogin again.\n\nThis API endpoint uses the `User-Interactive Authentication API`_.\n\nAn access token should be submitted to this endpoint if the client has\nan active session.\n\nThe homeserver may change the flows available depending on whether a\nvalid access token is provided.",
"operationId": "deactivateAccount",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"auth": {
"additionalProperties": {
"description": "Keys dependent on the login type",
"type": "object"
},
"description": "Additional authentication information for the user-interactive authentication API.",
"example": {
"example_credential": "verypoorsharedsecret",
"session": "xxxxx",
"type": "example.type.foo"
},
"properties": {
"session": {
"description": "The value of the session key given by the homeserver.",
"type": "string"
},
"type": {
"description": "The login type that the client is attempting to complete.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Authentication Data",
"type": "object"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The account has been deactivated.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"401": {
"description": "The homeserver requires additional authentication information.",
"schema": {
"description": "Used by servers to indicate that additional authentication information is required,",
"properties": {
"completed": {
"description": "A list of the stages the client has completed successfully",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
},
"flows": {
"description": "A list of the login flows supported by the server for this API.",
"items": {
"properties": {
"stages": {
"description": "The login type of each of the stages required to complete this\nauthentication flow",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
}
},
"required": [
"stages"
],
"type": "object"
},
"title": "Flow information",
"type": "array"
},
"params": {
"additionalProperties": {
"type": "object"
},
"description": "Contains any information that the client will need to know in order to\nuse a given type of authentication. For each login type presented,\nthat type may be present as a key in this dictionary. For example, the\npublic part of an OAuth client ID could be given here.",
"example": {
"example.type.baz": {
"example_key": "foobar"
}
},
"type": "object"
},
"session": {
"description": "This is a session identifier that the client must pass back to the home\nserver, if one is provided, in subsequent attempts to authenticate in the\nsame API call.",
"example": "xxxxxxyz",
"type": "string"
}
},
"required": [
"flows"
],
"title": "Authentication response",
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Deactivate a user's account.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/account/password": {
"post": {
"description": "Changes the password for an account on this homeserver.\n\nThis API endpoint uses the `User-Interactive Authentication API`_.\n\nAn access token should be submitted to this endpoint if the client has\nan active session.\n\nThe homeserver may change the flows available depending on whether a\nvalid access token is provided.",
"operationId": "changePassword",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"auth": {
"additionalProperties": {
"description": "Keys dependent on the login type",
"type": "object"
},
"description": "Additional authentication information for the user-interactive authentication API.",
"example": {
"example_credential": "verypoorsharedsecret",
"session": "xxxxx",
"type": "example.type.foo"
},
"properties": {
"session": {
"description": "The value of the session key given by the homeserver.",
"type": "string"
},
"type": {
"description": "The login type that the client is attempting to complete.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Authentication Data",
"type": "object"
},
"new_password": {
"description": "The new password for the account.",
"example": "ihatebananas",
"type": "string"
}
},
"required": [
"new_password"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The password has been changed.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"401": {
"description": "The homeserver requires additional authentication information.",
"schema": {
"description": "Used by servers to indicate that additional authentication information is required,",
"properties": {
"completed": {
"description": "A list of the stages the client has completed successfully",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
},
"flows": {
"description": "A list of the login flows supported by the server for this API.",
"items": {
"properties": {
"stages": {
"description": "The login type of each of the stages required to complete this\nauthentication flow",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
}
},
"required": [
"stages"
],
"type": "object"
},
"title": "Flow information",
"type": "array"
},
"params": {
"additionalProperties": {
"type": "object"
},
"description": "Contains any information that the client will need to know in order to\nuse a given type of authentication. For each login type presented,\nthat type may be present as a key in this dictionary. For example, the\npublic part of an OAuth client ID could be given here.",
"example": {
"example.type.baz": {
"example_key": "foobar"
}
},
"type": "object"
},
"session": {
"description": "This is a session identifier that the client must pass back to the home\nserver, if one is provided, in subsequent attempts to authenticate in the\nsame API call.",
"example": "xxxxxxyz",
"type": "string"
}
},
"required": [
"flows"
],
"title": "Authentication response",
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Changes a user's password.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/account/whoami": {
"get": {
"description": "Gets information about the owner of a given access token. \n\nNote that, as with the rest of the Client-Server API, \nApplication Services may masquerade as users within their \nnamespace by giving a ``user_id`` query parameter. In this \nsituation, the server should verify that the given ``user_id``\nis registered by the appservice, and return it in the response \nbody.",
"operationId": "getTokenOwner",
"parameters": [],
"responses": {
"200": {
"description": "The token belongs to a known user.",
"examples": {
"application/json": {
"user_id": "@joe:example.org"
}
},
"schema": {
"properties": {
"user_id": {
"description": "The user id that owns the access token.",
"type": "string"
}
},
"required": [
"user_id"
],
"type": "object"
}
},
"401": {
"description": "The token is not recognised",
"examples": {
"application/json": {
"errcode": "M_UNKNOWN_TOKEN",
"error": "Unrecognised access token."
}
},
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
},
"403": {
"description": "The appservice cannot masquerade as the user or has not registered them.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "Application service has not registered this user."
}
},
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets information about the owner of an access token.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/admin/whois/{userId}": {
"get": {
"description": "Gets information about a particular user.\n\nThis API may be restricted to only be called by the user being looked\nup, or by a server admin. Server-local administrator privileges are not\nspecified in this document.",
"operationId": "getWhoIs",
"parameters": [
{
"description": "The user to look up.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@peter:rabbit.rocks"
}
],
"responses": {
"200": {
"description": "The lookup was successful.",
"examples": {
"application/json": {
"devices": {
"teapot": {
"sessions": [
{
"connections": [
{
"ip": "127.0.0.1",
"last_seen": 1411996332123,
"user_agent": "curl/7.31.0-DEV"
},
{
"ip": "10.0.0.2",
"last_seen": 1411996332123,
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36"
}
]
}
]
}
},
"user_id": "@peter:rabbit.rocks"
}
},
"schema": {
"properties": {
"devices": {
"additionalProperties": {
"properties": {
"sessions": {
"description": "A user's sessions (i.e. what they did with an access token from one login).",
"items": {
"properties": {
"connections": {
"description": "Information particular connections in the session.",
"items": {
"properties": {
"ip": {
"description": "Most recently seen IP address of the session.",
"type": "string"
},
"last_seen": {
"description": "Unix timestamp that the session was last active.",
"type": "number"
},
"user_agent": {
"description": "User agent string last seen in the session.",
"type": "string"
}
},
"title": "ConnectionInfo",
"type": "object"
},
"type": "array"
}
},
"title": "SessionInfo",
"type": "object"
},
"type": "array"
}
},
"title": "DeviceInfo",
"type": "object"
},
"description": "Each key is an identitfier for one of the user's devices.",
"type": "object"
},
"user_id": {
"description": "The Matrix user ID of the user.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets information about a particular user.",
"tags": [
"Server administration"
]
}
},
"/_matrix/client/r0/createRoom": {
"post": {
"description": "Create a new room with various configuration options.\n\nThe server MUST apply the normal state resolution rules when creating\nthe new room, including checking power levels for each event. It MUST\napply the events implied by the request in the following order:\n\n0. A default ``m.room.power_levels`` event, giving the room creator\n (and not other members) permission to send state events.\n\n1. Events set by ``presets``.\n\n2. Events listed in ``initial_state``, in the order that they are\n listed.\n\n3. Events implied by ``name`` and ``topic``.\n\n4. Invite events implied by ``invite`` and ``invite_3pid``.",
"operationId": "createRoom",
"parameters": [
{
"description": "The desired room configuration.",
"in": "body",
"name": "body",
"schema": {
"example": {
"creation_content": {
"m.federate": false
},
"name": "The Grand Duke Pub",
"preset": "public_chat",
"room_alias_name": "thepub",
"topic": "All about happy hour"
},
"properties": {
"creation_content": {
"description": "Extra keys to be added to the content of the ``m.room.create``.\nThe server will clobber the following keys: ``creator``. Future\nversions of the specification may allow the server to clobber\nother keys.",
"title": "CreationContent",
"type": "object"
},
"guest_can_join": {
"description": "Allows guests to join the room. See `Guest Access`_ for more information.",
"type": "boolean"
},
"initial_state": {
"description": "A list of state events to set in the new room. This allows\nthe user to override the default state events set in the new\nroom. The expected format of the state events are an object\nwith type, state_key and content keys set.\n\nTakes precedence over events set by ``presets``, but gets\noverriden by ``name`` and ``topic`` keys.",
"items": {
"properties": {
"content": {
"type": "object"
},
"state_key": {
"type": "string"
},
"type": {
"type": "string"
}
},
"title": "StateEvent",
"type": "object"
},
"type": "array"
},
"invite": {
"description": "A list of user IDs to invite to the room. This will tell the\nserver to invite everyone in the list to the newly created room.",
"items": {
"type": "string"
},
"type": "array"
},
"invite_3pid": {
"description": "A list of objects representing third party IDs to invite into\nthe room.",
"items": {
"properties": {
"address": {
"description": "The invitee's third party identifier.",
"type": "string"
},
"id_server": {
"description": "The hostname+port of the identity server which should be used for third party identifier lookups.",
"type": "string"
},
"medium": {
"description": "The kind of address being passed in the address field, for example ``email``.",
"type": "string"
}
},
"required": [
"id_server",
"medium",
"address"
],
"title": "Invite3pid",
"type": "object"
},
"type": "array"
},
"is_direct": {
"description": "This flag makes the server set the ``is_direct`` flag on the\n``m.room.member`` events sent to the users in ``invite`` and\n``invite_3pid``. See `Direct Messaging`_ for more information.",
"type": "boolean"
},
"name": {
"description": "If this is included, an ``m.room.name`` event will be sent\ninto the room to indicate the name of the room. See Room\nEvents for more information on ``m.room.name``.",
"type": "string"
},
"preset": {
"description": "Convenience parameter for setting various default state events\nbased on a preset. Must be either:\n\n``private_chat`` =>\n ``join_rules`` is set to ``invite``.\n ``history_visibility`` is set to ``shared``.\n\n``trusted_private_chat`` =>\n ``join_rules`` is set to ``invite``.\n ``history_visibility`` is set to ``shared``.\n All invitees are given the same power level as the room creator.\n\n``public_chat``: =>\n ``join_rules`` is set to ``public``.\n ``history_visibility`` is set to ``shared``.",
"enum": [
"private_chat",
"public_chat",
"trusted_private_chat"
],
"type": "string"
},
"room_alias_name": {
"description": "The desired room alias **local part**. If this is included, a\nroom alias will be created and mapped to the newly created\nroom. The alias will belong on the *same* homeserver which\ncreated the room. For example, if this was set to \"foo\" and\nsent to the homeserver \"example.com\" the complete room alias\nwould be ``#foo:example.com``.",
"type": "string"
},
"topic": {
"description": "If this is included, an ``m.room.topic`` event will be sent\ninto the room to indicate the topic for the room. See Room\nEvents for more information on ``m.room.topic``.",
"type": "string"
},
"visibility": {
"description": "A ``public`` visibility indicates that the room will be shown\nin the published room list. A ``private`` visibility will hide\nthe room from the published room list. Rooms default to\n``private`` visibility if this key is not included. NB: This\nshould not be confused with ``join_rules`` which also uses the\nword ``public``.",
"enum": [
"public",
"private"
],
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "Information about the newly created room.",
"examples": {
"application/json": {
"room_id": "!sefiuhWgwghwWgh:example.com"
}
},
"schema": {
"description": "Information about the newly created room.",
"properties": {
"room_id": {
"description": "The created room's ID.",
"type": "string"
}
},
"type": "object"
}
},
"400": {
"description": "\nThe request is invalid. A meaningful ``errcode`` and description\nerror text will be returned. Example reasons for rejection include:\n\n- The request body is malformed (``errcode`` set to ``M_BAD_JSON``\n or ``M_NOT_JSON``).\n\n- The room alias specified is already taken (``errcode`` set to\n ``M_ROOM_IN_USE``).\n\n- The initial state implied by the parameters to the request is\n invalid: for example, the user's ``power_level`` is set below\n that necessary to set the room name (``errcode`` set to\n ``M_INVALID_ROOM_STATE``)."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Create a new room",
"tags": [
"Room creation"
]
}
},
"/_matrix/client/r0/delete_devices": {
"post": {
"description": "This API endpoint uses the `User-Interactive Authentication API`_.\n\nDeletes the given devices, and invalidates any access token associated with them.",
"operationId": "deleteDevices",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"auth": {
"additionalProperties": {
"description": "Keys dependent on the login type",
"type": "object"
},
"description": "Additional authentication information for the\nuser-interactive authentication API.",
"example": {
"example_credential": "verypoorsharedsecret",
"session": "xxxxx",
"type": "example.type.foo"
},
"properties": {
"session": {
"description": "The value of the session key given by the homeserver.",
"type": "string"
},
"type": {
"description": "The login type that the client is attempting to complete.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Authentication Data",
"type": "object"
},
"devices": {
"description": "The list of device IDs to delete.",
"example": [
"QBUAZIFURK",
"AUIECTSRND"
],
"items": {
"description": "A list of device IDs.",
"type": "string"
},
"type": "array"
}
},
"required": [
"devices"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The devices were successfully removed, or had been removed\npreviously.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"401": {
"description": "The homeserver requires additional authentication information.",
"schema": {
"description": "Used by servers to indicate that additional authentication information is required,",
"properties": {
"completed": {
"description": "A list of the stages the client has completed successfully",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
},
"flows": {
"description": "A list of the login flows supported by the server for this API.",
"items": {
"properties": {
"stages": {
"description": "The login type of each of the stages required to complete this\nauthentication flow",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
}
},
"required": [
"stages"
],
"type": "object"
},
"title": "Flow information",
"type": "array"
},
"params": {
"additionalProperties": {
"type": "object"
},
"description": "Contains any information that the client will need to know in order to\nuse a given type of authentication. For each login type presented,\nthat type may be present as a key in this dictionary. For example, the\npublic part of an OAuth client ID could be given here.",
"example": {
"example.type.baz": {
"example_key": "foobar"
}
},
"type": "object"
},
"session": {
"description": "This is a session identifier that the client must pass back to the home\nserver, if one is provided, in subsequent attempts to authenticate in the\nsame API call.",
"example": "xxxxxxyz",
"type": "string"
}
},
"required": [
"flows"
],
"title": "Authentication response",
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Bulk deletion of devices",
"tags": [
"Device management"
]
}
},
"/_matrix/client/r0/devices": {
"get": {
"description": "Gets information about all devices for the current user.",
"operationId": "getDevices",
"responses": {
"200": {
"description": "Device information",
"examples": {
"application/json": {
"devices": [
{
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
]
}
},
"schema": {
"properties": {
"devices": {
"description": "A list of all registered devices for this user.",
"items": {
"allOf": [
{
"description": "A client device",
"properties": {
"device_id": {
"description": "Identifier of this device.",
"example": "QBUAZIFURK",
"type": "string"
},
"display_name": {
"description": "Display name set by the user for this device. Absent if no name has been\nset.",
"example": "android",
"type": "string"
},
"last_seen_ip": {
"description": "The IP address where this device was last seen. (May be a few minutes out\nof date, for efficiency reasons).",
"example": "1.2.3.4",
"type": "string"
},
"last_seen_ts": {
"description": "The timestamp (in milliseconds since the unix epoch) when this devices\nwas last seen. (May be a few minutes out of date, for efficiency\nreasons).",
"example": 1474491775024,
"format": "int64",
"type": "integer"
}
},
"required": [
"device_id"
],
"title": "Device",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "List registered devices for the current user",
"tags": [
"Device management"
]
}
},
"/_matrix/client/r0/devices/{deviceId}": {
"delete": {
"description": "This API endpoint uses the `User-Interactive Authentication API`_.\n\nDeletes the given device, and invalidates any access token associated with it.",
"operationId": "deleteDevice",
"parameters": [
{
"description": "The device to delete.",
"in": "path",
"name": "deviceId",
"required": true,
"type": "string",
"x-example": "QBUAZIFURK"
},
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"auth": {
"additionalProperties": {
"description": "Keys dependent on the login type",
"type": "object"
},
"description": "Additional authentication information for the\nuser-interactive authentication API.",
"example": {
"example_credential": "verypoorsharedsecret",
"session": "xxxxx",
"type": "example.type.foo"
},
"properties": {
"session": {
"description": "The value of the session key given by the homeserver.",
"type": "string"
},
"type": {
"description": "The login type that the client is attempting to complete.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Authentication Data",
"type": "object"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The device was successfully removed, or had been removed\npreviously.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"401": {
"description": "The homeserver requires additional authentication information.",
"schema": {
"description": "Used by servers to indicate that additional authentication information is required,",
"properties": {
"completed": {
"description": "A list of the stages the client has completed successfully",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
},
"flows": {
"description": "A list of the login flows supported by the server for this API.",
"items": {
"properties": {
"stages": {
"description": "The login type of each of the stages required to complete this\nauthentication flow",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
}
},
"required": [
"stages"
],
"type": "object"
},
"title": "Flow information",
"type": "array"
},
"params": {
"additionalProperties": {
"type": "object"
},
"description": "Contains any information that the client will need to know in order to\nuse a given type of authentication. For each login type presented,\nthat type may be present as a key in this dictionary. For example, the\npublic part of an OAuth client ID could be given here.",
"example": {
"example.type.baz": {
"example_key": "foobar"
}
},
"type": "object"
},
"session": {
"description": "This is a session identifier that the client must pass back to the home\nserver, if one is provided, in subsequent attempts to authenticate in the\nsame API call.",
"example": "xxxxxxyz",
"type": "string"
}
},
"required": [
"flows"
],
"title": "Authentication response",
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Delete a device",
"tags": [
"Device management"
]
},
"get": {
"description": "Gets information on a single device, by device id.",
"operationId": "getDevice",
"parameters": [
{
"description": "The device to retrieve.",
"in": "path",
"name": "deviceId",
"required": true,
"type": "string",
"x-example": "QBUAZIFURK"
}
],
"responses": {
"200": {
"description": "Device information",
"examples": {
"application/json": {
"device_id": "QBUAZIFURK",
"display_name": "android",
"last_seen_ip": "1.2.3.4",
"last_seen_ts": 1474491775024
}
},
"schema": {
"allOf": [
{
"description": "A client device",
"properties": {
"device_id": {
"description": "Identifier of this device.",
"example": "QBUAZIFURK",
"type": "string"
},
"display_name": {
"description": "Display name set by the user for this device. Absent if no name has been\nset.",
"example": "android",
"type": "string"
},
"last_seen_ip": {
"description": "The IP address where this device was last seen. (May be a few minutes out\nof date, for efficiency reasons).",
"example": "1.2.3.4",
"type": "string"
},
"last_seen_ts": {
"description": "The timestamp (in milliseconds since the unix epoch) when this devices\nwas last seen. (May be a few minutes out of date, for efficiency\nreasons).",
"example": 1474491775024,
"format": "int64",
"type": "integer"
}
},
"required": [
"device_id"
],
"title": "Device",
"type": "object"
}
],
"type": "object"
}
},
"404": {
"description": "The current user has no device with the given ID."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get a single device",
"tags": [
"Device management"
]
},
"put": {
"description": "Updates the metadata on the given device.",
"operationId": "updateDevice",
"parameters": [
{
"description": "The device to update.",
"in": "path",
"name": "deviceId",
"required": true,
"type": "string",
"x-example": "QBUAZIFURK"
},
{
"description": "New information for the device.",
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"display_name": {
"description": "The new display name for this device. If not given, the\ndisplay name is unchanged.",
"example": "My other phone",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The device was successfully updated.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"404": {
"description": "The current user has no device with the given ID."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Update a device",
"tags": [
"Device management"
]
}
},
"/_matrix/client/r0/directory/room/{roomAlias}": {
"delete": {
"description": "Remove a mapping of room alias to room ID.\n\nServers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.",
"operationId": "deleteRoomAlias",
"parameters": [
{
"description": "The room alias to remove.",
"in": "path",
"name": "roomAlias",
"required": true,
"type": "string",
"x-example": "#monkeys:matrix.org"
}
],
"responses": {
"200": {
"description": "The mapping was deleted.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Remove a mapping of room alias to room ID.",
"tags": [
"Room directory"
]
},
"get": {
"description": "Requests that the server resolve a room alias to a room ID.\n\nThe server will use the federation API to resolve the alias if the\ndomain part of the alias does not correspond to the server's own\ndomain.",
"operationId": "getRoomIdByAlias",
"parameters": [
{
"description": "The room alias.",
"in": "path",
"name": "roomAlias",
"required": true,
"type": "string",
"x-example": "#monkeys:matrix.org"
}
],
"responses": {
"200": {
"description": "The room ID and other information for this alias.",
"examples": {
"application/json": {
"room_id": "!abnjk1jdasj98:capuchins.com",
"servers": [
"capuchins.com",
"matrix.org",
"another.com"
]
}
},
"schema": {
"properties": {
"room_id": {
"description": "The room ID for this room alias.",
"type": "string"
},
"servers": {
"description": "A list of servers that are aware of this room alias.",
"items": {
"description": "A server which is aware of this room alias.",
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"404": {
"description": "There is no mapped room ID for this room alias.",
"examples": {
"application/json": {
"errcode": "M_NOT_FOUND",
"error": "Room alias #monkeys:matrix.org not found."
}
}
}
},
"summary": "Get the room ID corresponding to this room alias.",
"tags": [
"Room directory"
]
},
"put": {
"operationId": "setRoomAlias",
"parameters": [
{
"description": "The room alias to set.",
"in": "path",
"name": "roomAlias",
"required": true,
"type": "string",
"x-example": "#monkeys:matrix.org"
},
{
"description": "Information about this room alias.",
"in": "body",
"name": "roomInfo",
"required": true,
"schema": {
"example": {
"room_id": "!abnjk1jdasj98:capuchins.com"
},
"properties": {
"room_id": {
"description": "The room ID to set.",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The mapping was created.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"409": {
"description": "A room alias with that name already exists.",
"examples": {
"application/json": {
"errcode": "M_UNKNOWN",
"error": "Room alias #monkeys:matrix.org already exists."
}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Create a new mapping from room alias to room ID.",
"tags": [
"Room directory"
]
}
},
"/_matrix/client/r0/events": {
"get": {
"deprecated": true,
"description": "This will listen for new events and return them to the caller. This will\nblock until an event is received, or until the ``timeout`` is reached.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the |/sync|_ API with a ``since`` parameter. See\nthe `migration guide\n<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.",
"operationId": "getEvents",
"parameters": [
{
"description": "The token to stream from. This token is either from a previous\nrequest to this API or from the initial sync API.",
"in": "query",
"name": "from",
"required": false,
"type": "string",
"x-example": "s3456_9_0"
},
{
"description": "The maximum time in milliseconds to wait for an event.",
"in": "query",
"name": "timeout",
"required": false,
"type": "integer",
"x-example": "35000"
}
],
"responses": {
"200": {
"description": "The events received, which may be none.",
"examples": {
"application/json": {
"chunk": [
{
"age": 32,
"content": {
"body": "incoming message",
"msgtype": "m.text"
},
"event_id": "$14328055551tzaee:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"sender": "@bob:localhost",
"type": "m.room.message"
}
],
"end": "s3457_9_0",
"start": "s3456_9_0"
}
},
"schema": {
"properties": {
"chunk": {
"description": "An array of events.",
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"end": {
"description": "A token which correlates to the last value in ``chunk``. This\ntoken should be used in the next request to ``/events``.",
"type": "string"
},
"start": {
"description": "A token which correlates to the first value in ``chunk``. This\nis usually the same token supplied to ``from=``.",
"type": "string"
}
},
"type": "object"
}
},
"400": {
"description": "Bad pagination ``from`` parameter."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Listen on the event stream.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/events/{eventId}": {
"get": {
"deprecated": true,
"description": "Get a single event based on ``event_id``. You must have permission to\nretrieve this event e.g. by being a member in the room for this event.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the |/rooms/{roomId}/event/{eventId}|_ API\nor the |/rooms/{roomId}/context/{eventId}|_ API.",
"operationId": "getOneEvent",
"parameters": [
{
"description": "The event ID to get.",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "$asfDuShaf7Gafaw:matrix.org"
}
],
"responses": {
"200": {
"description": "The full event.",
"examples": {
"application/json": {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"type": "m.room.message"
}
},
"schema": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
]
}
},
"404": {
"description": "The event was not found or you do not have permission to read this event."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get a single event by event ID.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/initialSync": {
"get": {
"deprecated": true,
"description": "This returns the full state for this user, with an optional limit on the\nnumber of messages per room to return.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the |/sync|_ API with no ``since`` parameter. See\nthe `migration guide\n<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.",
"operationId": "initialSync",
"parameters": [
{
"description": "The maximum number of messages to return for each room.",
"in": "query",
"name": "limit",
"required": false,
"type": "integer",
"x-example": "2"
},
{
"description": "Whether to include rooms that the user has left. If ``false`` then\nonly rooms that the user has been invited to or has joined are\nincluded. If set to ``true`` then rooms that the user has left are\nincluded as well. By default this is ``false``.",
"in": "query",
"name": "archived",
"required": false,
"type": "boolean",
"x-example": "true"
}
],
"responses": {
"200": {
"description": "The user's current state.",
"examples": {
"application/json": {
"account_data": [
{
"content": {
"custom_config_key": "custom_config_value"
},
"type": "org.example.custom.config"
}
],
"end": "s3456_9_0",
"presence": [
{
"content": {
"avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
"displayname": "Bob",
"last_active_ago": 31053,
"presence": "online",
"user_id": "@bob:localhost"
},
"type": "m.presence"
}
],
"rooms": [
{
"account_data": [
{
"content": {
"tags": {
"work": {
"order": 1
}
}
},
"type": "m.tag"
},
{
"content": {
"custom_config_key": "custom_config_value"
},
"type": "org.example.custom.room.config"
}
],
"membership": "join",
"messages": {
"chunk": [
{
"age": 343513403,
"content": {
"body": "foo",
"msgtype": "m.text"
},
"event_id": "$14328044851tzTJS:localhost",
"origin_server_ts": 1432804485886,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"sender": "@alice:localhost",
"type": "m.room.message"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:localhost",
"origin_server_ts": 1432804487480,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"sender": "@bob:localhost",
"type": "m.room.message"
}
],
"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",
"sender": "@alice:localhost",
"state_key": "",
"type": "m.room.join_rules"
},
{
"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",
"sender": "@alice:localhost",
"state_key": "@alice:localhost",
"type": "m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:localhost"
},
"event_id": "$14259997320KhbwJ:localhost",
"origin_server_ts": 1425999732089,
"room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
"sender": "@alice:localhost",
"state_key": "",
"type": "m.room.create"
},
{
"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",
"sender": "@bob:localhost",
"state_key": "@bob:localhost",
"type": "m.room.member"
},
{
"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",
"sender": "@alice:localhost",
"state_key": "",
"type": "m.room.power_levels"
}
],
"visibility": "private"
}
]
}
},
"schema": {
"properties": {
"account_data": {
"description": "The global private data created by this user.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"end": {
"description": "A token which correlates to the last value in ``chunk``. This\ntoken should be used with the ``/events`` API to listen for new\nevents.",
"type": "string"
},
"presence": {
"description": "A list of presence events.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"rooms": {
"items": {
"properties": {
"account_data": {
"description": "The private data that this user has attached to\nthis room.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"invite": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
],
"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.\n\nThe following membership states are specified:\n\n- ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.\n\n- ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.\n\n- ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).\n\n- ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).\n\n- ``knock`` - This is a reserved word, which currently has no meaning.\n\nThe ``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.\n\nThis 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 subset of state events such as the room name.",
"properties": {
"content": {
"properties": {
"avatar_url": {
"description": "The avatar URL for this user, if any. This is added by the homeserver.",
"type": "string"
},
"displayname": {
"description": "The display name for this user, if any. This is added by the homeserver.",
"type": [
"string",
"null"
]
},
"is_direct": {
"description": "Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.",
"type": "boolean"
},
"membership": {
"description": "The membership state of the user.",
"enum": [
"invite",
"join",
"knock",
"leave",
"ban"
],
"type": "string"
},
"third_party_invite": {
"properties": {
"display_name": {
"description": "A name which can be displayed to represent the user instead of their third party identifier",
"type": "string"
},
"signed": {
"description": "A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.",
"properties": {
"mxid": {
"description": "The invited matrix user ID. Must be equal to the user_id property of the event.",
"type": "string"
},
"signatures": {
"description": "A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.",
"title": "Signatures",
"type": "object"
},
"token": {
"description": "The token property of the containing third_party_invite object.",
"type": "string"
}
},
"required": [
"mxid",
"signatures",
"token"
],
"title": "signed",
"type": "object"
}
},
"required": [
"display_name",
"signed"
],
"title": "Invite",
"type": "object"
}
},
"required": [
"membership"
],
"title": "EventContent",
"type": "object"
},
"invite_room_state": {
"description": "A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.",
"items": {
"description": "A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.",
"properties": {
"content": {
"description": "The ``content`` for the event.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "The ``state_key`` for the event.",
"type": "string"
},
"type": {
"description": "The ``type`` for the event.",
"type": "string"
}
},
"required": [
"type",
"state_key",
"content"
],
"title": "StrippedState",
"type": "object"
},
"type": "array"
},
"state_key": {
"description": "The ``user_id`` this membership event relates to.",
"type": "string"
},
"type": {
"enum": [
"m.room.member"
],
"type": "string"
}
},
"title": "The current membership state of a user in the room.",
"type": "object"
}
],
"description": "The invite event if ``membership`` is ``invite``",
"title": "InviteEvent",
"type": "object"
},
"membership": {
"description": "The user's membership state in this room.",
"enum": [
"invite",
"join",
"leave",
"ban"
],
"type": "string"
},
"messages": {
"description": "The pagination chunk for this room.",
"properties": {
"chunk": {
"description": "If the user is a member of the room this will be a\nlist of the most recent messages for this room. If\nthe user has left the room this will be the\nmessages that preceeded them leaving. This array\nwill consist of at most ``limit`` elements.",
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"title": "RoomEvent",
"type": "object"
},
"type": "array"
},
"end": {
"description": "A token which correlates to the last value in ``chunk``.\nUsed for pagination.",
"type": "string"
},
"start": {
"description": "A token which correlates to the first value in ``chunk``.\nUsed for pagination.",
"type": "string"
}
},
"required": [
"start",
"end",
"chunk"
],
"title": "PaginationChunk",
"type": "object"
},
"room_id": {
"description": "The ID of this room.",
"type": "string"
},
"state": {
"description": "If the user is a member of the room this will be the\ncurrent state of the room as a list of events. If the\nuser has left the room this will be the state of the\nroom when they left it.",
"items": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
],
"title": "StateEvent",
"type": "object"
},
"type": "array"
},
"visibility": {
"description": "Whether this room is visible to the ``/publicRooms`` API\nor not.\"",
"enum": [
"private",
"public"
],
"type": "string"
}
},
"required": [
"room_id",
"membership"
],
"title": "RoomInfo",
"type": "object"
},
"type": "array"
}
},
"required": [
"end",
"rooms",
"presence"
],
"type": "object"
}
},
"404": {
"description": "There is no avatar URL for this user or this user does not exist."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get the user's current state.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/join/{roomIdOrAlias}": {
"post": {
"description": "*Note that this API takes either a room ID or alias, unlike* ``/room/{roomId}/join``.\n\nThis API starts a user participating in a particular room, if that user\nis allowed to participate in that room. After this call, the client is\nallowed to see all current state events in the room, and all subsequent\nevents associated with the room until the user leaves the room.\n\nAfter a user has joined a room, the room will appear as an entry in the\nresponse of the |/initialSync|_ and |/sync|_ APIs.\n\nIf a ``third_party_signed`` was supplied, the homeserver must verify\nthat it matches a pending ``m.room.third_party_invite`` event in the\nroom, and perform key validity checking if required by the event.",
"operationId": "joinRoom",
"parameters": [
{
"description": "The room identifier or alias to join.",
"in": "path",
"name": "roomIdOrAlias",
"required": true,
"type": "string",
"x-example": "#monkeys:matrix.org"
},
{
"in": "body",
"name": "third_party_signed",
"schema": {
"example": {
"third_party_signed": {
"signed": {
"mxid": "@green:eggs.ham",
"sender": "@cat:the.hat",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
},
"token": "random8nonce"
}
}
},
"properties": {
"third_party_signed": {
"description": "A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.",
"properties": {
"signed": {
"properties": {
"mxid": {
"description": "The Matrix ID of the invitee.",
"type": "string"
},
"sender": {
"description": "The Matrix ID of the user who issued the invite.",
"type": "string"
},
"signatures": {
"description": "A signatures object containing a signature of the entire signed object.",
"title": "Signatures",
"type": "object"
},
"token": {
"description": "The state key of the m.third_party_invite event.",
"type": "string"
}
},
"required": [
"sender",
"mxid",
"token",
"signatures"
],
"title": "Signed",
"type": "object"
}
},
"required": [
"signed"
],
"title": "ThirdPartySigned",
"type": "object"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The room has been joined.\n\nThe joined room ID must be returned in the ``room_id`` field.",
"examples": {
"application/json": {
"room_id": "!d41d8cd:matrix.org"
}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:\n\n- The room is invite-only and the user was not invited.\n- The user has been banned from the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Start the requesting user participating in a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/joined_rooms": {
"get": {
"description": "This API returns a list of the user's current rooms.",
"operationId": "getJoinedRooms",
"responses": {
"200": {
"description": "A list of the rooms the user is in.",
"examples": {
"application/json": {
"joined_rooms": [
"!foo:example.com"
]
}
},
"schema": {
"properties": {
"joined_rooms": {
"description": "The ID of each room in which the user has ``joined`` membership.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"joined_rooms"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Lists the user's current rooms.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/keys/changes": {
"get": {
"description": "Gets a list of users who have updated their device identity keys since a\nprevious sync token.\n\nThe server should include in the results any users who:\n\n* currently share a room with the calling user (ie, both users have\n membership state ``join``); *and*\n* added new device identity keys or removed an existing device with\n identity keys, between ``from`` and ``to``.",
"operationId": "getKeysChanges",
"parameters": [
{
"description": "The desired start point of the list. Should be the ``next_batch`` field\nfrom a response to an earlier call to |/sync|. Users who have not\nuploaded new device identity keys since this point, nor deleted\nexisting devices with identity keys since then, will be excluded\nfrom the results.",
"in": "query",
"name": "from",
"required": true,
"type": "string",
"x-example": "s72594_4483_1934"
},
{
"description": "The desired end point of the list. Should be the ``next_batch``\nfield from a recent call to |/sync| - typically the most recent\nsuch call. This may be used by the server as a hint to check its\ncaches are up to date.",
"in": "query",
"name": "to",
"required": true,
"type": "string",
"x-example": "s75689_5632_2435"
}
],
"responses": {
"200": {
"description": "The list of users who updated their devices.",
"schema": {
"properties": {
"changed": {
"description": "The Matrix User IDs of all users who updated their device\nidentity keys.",
"example": [
"@alice:example.com",
"@bob:example.org"
],
"items": {
"type": "string"
},
"type": "array"
},
"left": {
"description": "The Matrix User IDs of all users who may have left all\nthe end-to-end encrypted rooms they previously shared\nwith the user.",
"example": [
"@clara:example.com",
"@doug:example.org"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Query users with recent device key updates.",
"tags": [
"End-to-end encryption"
]
}
},
"/_matrix/client/r0/keys/claim": {
"post": {
"description": "Claims one-time keys for use in pre-key messages.",
"operationId": "claimKeys",
"parameters": [
{
"description": "Query defining the keys to be claimed",
"in": "body",
"name": "query",
"schema": {
"properties": {
"one_time_keys": {
"additionalProperties": {
"additionalProperties": {
"description": "algorithm",
"example": "signed_curve25519",
"type": "string"
},
"type": "object"
},
"description": "The keys to be claimed. A map from user ID, to a map from\ndevice ID to algorithm name.",
"example": {
"@alice:example.com": {
"JLAFKJWSCS": "curve25519"
}
},
"type": "object"
},
"timeout": {
"description": "The time (in milliseconds) to wait when downloading keys from\nremote servers. 10 seconds is the recommended default.",
"example": 10000,
"type": "integer"
}
},
"required": [
"one_time_keys"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The claimed keys",
"schema": {
"properties": {
"failures": {
"additionalProperties": {
"type": "object"
},
"description": "If any remote homeservers could not be reached, they are\nrecorded here. The names of the properties are the names of\nthe unreachable servers.\n\nIf the homeserver could be reached, but the user or device\nwas unknown, no failure is recorded. Instead, the corresponding\nuser or device is missing from the ``one_time_keys`` result.",
"example": {},
"type": "object"
},
"one_time_keys": {
"additionalProperties": {
"additionalProperties": {
"type": [
"string",
"object"
]
},
"type": "object"
},
"description": "One-time keys for the queried devices. A map from user ID, to a\nmap from ``<algorithm>:<key_id>`` to the key object.",
"example": {
"@alice:example.com": {
"JLAFKJWSCS": {
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
},
"type": "object"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Claim one-time encryption keys.",
"tags": [
"End-to-end encryption"
]
}
},
"/_matrix/client/r0/keys/query": {
"post": {
"description": "Returns the current devices and identity keys for the given users.",
"operationId": "queryKeys",
"parameters": [
{
"description": "Query defining the keys to be downloaded",
"in": "body",
"name": "query",
"schema": {
"properties": {
"device_keys": {
"additionalProperties": {
"items": {
"description": "device ID",
"type": "string"
},
"type": "array"
},
"description": "The keys to be downloaded. A map from user ID, to a list of\ndevice IDs, or to an empty list to indicate all devices for the\ncorresponding user.",
"example": {
"@alice:example.com": []
},
"type": "object"
},
"timeout": {
"description": "The time (in milliseconds) to wait when downloading keys from\nremote servers. 10 seconds is the recommended default.",
"example": 10000,
"type": "integer"
},
"token": {
"description": "If the client is fetching keys as a result of a device update received\nin a sync request, this should be the 'since' token of that sync request,\nor any later sync token. This allows the server to ensure its response\ncontains the keys advertised by the notification in that sync.",
"type": "string"
}
},
"required": [
"device_keys"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The device information",
"schema": {
"properties": {
"device_keys": {
"additionalProperties": {
"additionalProperties": {
"allOf": [
{
"description": "Device identity keys",
"properties": {
"algorithms": {
"description": "The encryption algorithms supported by this device.",
"example": [
"m.olm.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"items": {
"type": "string"
},
"type": "array"
},
"device_id": {
"description": "The ID of the device these keys belong to. Must match the device ID used\nwhen logging in.",
"example": "JLAFKJWSCS",
"type": "string"
},
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "Public identity keys. The names of the properties should be in the\nformat ``<algorithm>:<device_id>``. The keys themselves should be\nencoded as specified by the key algorithm.",
"example": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"type": "object"
},
"signatures": {
"additionalProperties": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"description": "Signatures for the device key object. A map from user ID, to a map from\n``<algorithm>:<device_id>`` to the signature.\n\nThe signature is calculated using the process described at `Signing\nJSON`_.",
"example": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"type": "object"
},
"user_id": {
"description": "The ID of the user the device belongs to. Must match the user ID used\nwhen logging in.",
"example": "@alice:example.com",
"type": "string"
}
},
"required": [
"user_id",
"device_id",
"algorithms",
"keys",
"signatures"
],
"title": "DeviceKeys",
"type": "object"
}
],
"properties": {
"unsigned": {
"description": "Additional data added to the device key information\nby intermediate servers, and not covered by the\nsignatures.",
"properties": {
"device_display_name": {
"description": "The display name which the user set on the device.",
"type": "string"
}
},
"title": "UnsignedDeviceInfo",
"type": "object"
}
}
},
"type": "object"
},
"description": "Information on the queried devices. A map from user ID, to a\nmap from device ID to device information. For each device,\nthe information returned will be the same as uploaded via\n``/keys/upload``, with the addition of an ``unsigned``\nproperty.",
"example": {
"@alice:example.com": {
"JLAFKJWSCS": {
"algorithms": [
"m.olm.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"device_id": "JLAFKJWSCS",
"keys": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"unsigned": {
"device_display_name": "Alice's mobile phone"
},
"user_id": "@alice:example.com"
}
}
},
"type": "object"
},
"failures": {
"additionalProperties": {
"type": "object"
},
"description": "If any remote homeservers could not be reached, they are\nrecorded here. The names of the properties are the names of\nthe unreachable servers.\n\nIf the homeserver could be reached, but the user or device\nwas unknown, no failure is recorded. Instead, the corresponding\nuser or device is missing from the ``device_keys`` result.",
"example": {},
"type": "object"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Download device identity keys.",
"tags": [
"End-to-end encryption"
]
}
},
"/_matrix/client/r0/keys/upload": {
"post": {
"description": "Publishes end-to-end encryption keys for the device.",
"operationId": "uploadKeys",
"parameters": [
{
"description": "The keys to be published",
"in": "body",
"name": "keys",
"schema": {
"properties": {
"device_keys": {
"allOf": [
{
"description": "Device identity keys",
"properties": {
"algorithms": {
"description": "The encryption algorithms supported by this device.",
"example": [
"m.olm.curve25519-aes-sha256",
"m.megolm.v1.aes-sha"
],
"items": {
"type": "string"
},
"type": "array"
},
"device_id": {
"description": "The ID of the device these keys belong to. Must match the device ID used\nwhen logging in.",
"example": "JLAFKJWSCS",
"type": "string"
},
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "Public identity keys. The names of the properties should be in the\nformat ``<algorithm>:<device_id>``. The keys themselves should be\nencoded as specified by the key algorithm.",
"example": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"type": "object"
},
"signatures": {
"additionalProperties": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"description": "Signatures for the device key object. A map from user ID, to a map from\n``<algorithm>:<device_id>`` to the signature.\n\nThe signature is calculated using the process described at `Signing\nJSON`_.",
"example": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
}
},
"type": "object"
},
"user_id": {
"description": "The ID of the user the device belongs to. Must match the user ID used\nwhen logging in.",
"example": "@alice:example.com",
"type": "string"
}
},
"required": [
"user_id",
"device_id",
"algorithms",
"keys",
"signatures"
],
"title": "DeviceKeys",
"type": "object"
}
],
"description": "Identity keys for the device. May be absent if no new\nidentity keys are required."
},
"one_time_keys": {
"additionalProperties": {
"type": [
"string",
"object"
]
},
"description": "One-time public keys for \"pre-key\" messages. The names of\nthe properties should be in the format\n``<algorithm>:<key_id>``. The format of the key is determined\nby the key algorithm.\n\nMay be absent if no new one-time keys are required.",
"example": {
"curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
"signed_curve25519:AAAAHQ": {
"key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
}
}
},
"signed_curve25519:AAAAHg": {
"key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures": {
"@alice:example.com": {
"ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
},
"type": "object"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The provided keys were sucessfully uploaded.",
"schema": {
"properties": {
"one_time_key_counts": {
"additionalProperties": {
"type": "integer"
},
"description": "For each key algorithm, the number of unclaimed one-time keys\nof that type currently held on the server for this device.",
"example": {
"curve25519": 10,
"signed_curve25519": 20
},
"type": "object"
}
},
"required": [
"one_time_key_counts"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Upload end-to-end encryption keys.",
"tags": [
"End-to-end encryption"
]
}
},
"/_matrix/client/r0/login": {
"post": {
"description": "Authenticates the user, and issues an access token they can\nuse to authorize themself in subsequent requests.\n\nIf the client does not supply a ``device_id``, the server must\nauto-generate one.\n\nThe returned access token must be associated with the ``device_id``\nsupplied by the client or generated by the server. The server may\ninvalidate any access token previously associated with that device. See\n`Relationship between access tokens and devices`_.",
"operationId": "login",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"example": {
"initial_device_display_name": "Jungle Phone",
"password": "ilovebananas",
"type": "m.login.password",
"user": "cheeky_monkey"
},
"properties": {
"address": {
"description": "Third party identifier for the user.",
"type": "string"
},
"device_id": {
"description": "ID of the client device. If this does not correspond to a\nknown client device, a new device will be created. The server\nwill auto-generate a device_id if this is not specified.",
"type": "string"
},
"initial_device_display_name": {
"description": "A display name to assign to the newly-created device. Ignored\nif ``device_id`` corresponds to a known device.",
"type": "string"
},
"medium": {
"description": "When logging in using a third party identifier, the medium of the identifier. Must be 'email'.",
"type": "string"
},
"password": {
"description": "Required when ``type`` is ``m.login.password``. The user's\npassword.",
"type": "string"
},
"token": {
"description": "Required when ``type`` is ``m.login.token``. Part of `Token-based`_ login.",
"type": "string"
},
"type": {
"description": "The login type being used.",
"enum": [
"m.login.password",
"m.login.token"
],
"type": "string"
},
"user": {
"description": "The fully qualified user ID or just local part of the user ID, to log in.",
"type": "string"
}
},
"required": [
"type"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been authenticated.",
"examples": {
"application/json": {
"access_token": "abc123",
"device_id": "GHTYAJCE",
"user_id": "@cheeky_monkey:matrix.org"
}
},
"schema": {
"properties": {
"access_token": {
"description": "An access token for the account.\nThis access token can then be used to authorize other requests.",
"type": "string"
},
"device_id": {
"description": "ID of the logged-in device. Will be the same as the\ncorresponding parameter in the request, if one was specified.",
"type": "string"
},
"home_server": {
"description": "The server_name of the homeserver on which the account has\nbeen registered.\n\n**Deprecated**. Clients should extract the server_name from\n``user_id`` (by splitting at the first colon) if they require\nit. Note also that ``homeserver`` is not spelt this way.",
"type": "string"
},
"user_id": {
"description": "The fully-qualified Matrix ID that has been registered.",
"type": "string"
}
},
"type": "object"
}
},
"400": {
"description": "Part of the request was invalid. For example, the login type may not be recognised.",
"examples": {
"application/json": {
"errcode": "M_UNKNOWN",
"error": "Bad login type."
}
}
},
"403": {
"description": "The login attempt failed. For example, the password may have been incorrect.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN"
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Authenticates the user.",
"tags": [
"Session management"
]
}
},
"/_matrix/client/r0/logout": {
"post": {
"description": "Invalidates an existing access token, so that it can no longer be used for\nauthorization.",
"operationId": "logout",
"responses": {
"200": {
"description": "The access token used in the request was succesfully invalidated.",
"schema": {
"properties": {},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Invalidates a user access token",
"tags": [
"Session management"
]
}
},
"/_matrix/client/r0/logout/all": {
"post": {
"description": "Invalidates all access tokens for a user, so that they can no longer be used for\nauthorization. This includes the access token that made this request. \n\nThis endpoint does not require UI authorization because UI authorization is\ndesigned to protect against attacks where the someone gets hold of a single access\ntoken then takes over the account. This endpoint invalidates all access tokens for\nthe user, including the token used in the request, and therefore the attacker is\nunable to take over the account in this way.",
"operationId": "logout_all",
"responses": {
"200": {
"description": "The user's access tokens were succesfully invalidated.",
"schema": {
"properties": {},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Invalidates all access tokens for a user",
"tags": [
"Session management"
]
}
},
"/_matrix/client/r0/notifications": {
"get": {
"description": "This API is used to paginate through the list of events that the\nuser has been, or would have been notified about.",
"operationId": "getNotifications",
"parameters": [
{
"description": "Pagination token given to retrieve the next set of events.",
"in": "query",
"name": "from",
"required": false,
"type": "string",
"x-example": "xxxxx"
},
{
"description": "Limit on the number of events to return in this request.",
"in": "query",
"name": "limit",
"required": false,
"type": "number",
"x-example": "20"
},
{
"description": "Allows basic filtering of events returned. Supply ``highlight``\nto return only events where the notification had the highlight\ntweak set.",
"in": "query",
"name": "only",
"required": false,
"type": "string",
"x-example": "highlight"
}
],
"responses": {
"200": {
"description": "A batch of events is being returned",
"examples": {
"application/json": {
"next_token": "abcdef",
"notifications": [
{
"actions": [
"notify"
],
"event": {
"age": 124524,
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"event_id": "$74686972643033:example.com",
"origin_server_ts": 1417731086797,
"sender": "@alice:example.com",
"txn_id": "1234",
"type": "m.room.message"
},
"profile_tag": "hcbvkzxhcvb",
"read": true,
"room_id": "!abcdefg:example.com",
"ts": 1475508881945
}
]
}
},
"schema": {
"properties": {
"next_token": {
"description": "The token to supply in the ``from`` param of the next\n``/notifications`` request in order to request more\nevents. If this is absent, there are no more results.",
"type": "string"
},
"notifications": {
"description": "The list of events that triggered notifications.",
"items": {
"properties": {
"actions": {
"description": "The action(s) to perform when the conditions for this rule are met.\nSee `Push Rules: API`_.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"event": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"description": "The Event object for the event that triggered the notification.",
"title": "Event",
"type": "object"
},
"profile_tag": {
"description": "The profile tag of the rule that matched this event.",
"type": "string"
},
"read": {
"description": "Indicates whether the user has sent a read receipt indicating\nthat they have read this message.",
"type": "boolean"
},
"room_id": {
"description": "The ID of the room in which the event was posted.",
"type": "string"
},
"ts": {
"description": "The unix timestamp at which the event notification was sent,\nin milliseconds.",
"type": "integer"
}
},
"required": [
"actions",
"event",
"read",
"room_id",
"ts"
],
"title": "Notification",
"type": "object"
},
"type": "array"
}
},
"required": [
"notifications"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets a list of events that the user has been notified about",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/presence/list/{userId}": {
"get": {
"description": "Retrieve a list of presence events for every user on this list.",
"operationId": "getPresenceForList",
"parameters": [
{
"description": "The user whose presence list should be retrieved.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
}
],
"responses": {
"200": {
"description": "A list of presence events for this list.",
"examples": {
"application/json": [
{
"content": {
"last_active_ago": 395,
"presence": "offline",
"user_id": "@alice:matrix.org"
},
"type": "m.presence"
},
{
"content": {
"currently_active": true,
"last_active_ago": 16874,
"presence": "online",
"user_id": "@marisa:matrix.org"
},
"type": "m.presence"
}
]
},
"schema": {
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"title": "PresenceEvent",
"type": "object"
},
"type": "array"
}
}
},
"summary": "Get presence events for this presence list.",
"tags": [
"Presence"
]
},
"post": {
"description": "Adds or removes users from this presence list.",
"operationId": "modifyPresenceList",
"parameters": [
{
"description": "The user whose presence list is being modified.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The modifications to make to this presence list.",
"in": "body",
"name": "presence_diff",
"required": true,
"schema": {
"example": {
"drop": [
"@alice:matrix.org"
],
"invite": [
"@bob:matrix.org"
]
},
"properties": {
"drop": {
"description": "A list of user IDs to remove from the list.",
"items": {
"description": "A list of user IDs.",
"type": "string"
},
"type": "array"
},
"invite": {
"description": "A list of user IDs to add to the list.",
"items": {
"description": "A list of user IDs.",
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The list was updated.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Add or remove users from this presence list.",
"tags": [
"Presence"
]
}
},
"/_matrix/client/r0/presence/{userId}/status": {
"get": {
"description": "Get the given user's presence state.",
"operationId": "getPresence",
"parameters": [
{
"description": "The user whose presence state to get.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
}
],
"responses": {
"200": {
"description": "The presence state for this user.",
"examples": {
"application/json": {
"last_active_ago": 420845,
"presence": "unavailable"
}
},
"schema": {
"properties": {
"currently_active": {
"description": "Whether the user is currently active",
"type": "boolean"
},
"last_active_ago": {
"description": "The length of time in milliseconds since an action was performed\nby this user.",
"type": "integer"
},
"presence": {
"description": "This user's presence.",
"enum": [
"online",
"offline",
"unavailable"
],
"type": "string"
},
"status_msg": {
"description": "The state message for this user if one was set.",
"type": [
"string",
"null"
]
}
},
"required": [
"presence"
],
"type": "object"
}
},
"404": {
"description": "There is no presence state for this user. This user may not exist or\nisn't exposing presence information to you."
}
},
"summary": "Get this user's presence state.",
"tags": [
"Presence"
]
},
"put": {
"description": "This API sets the given user's presence state. When setting the status,\nthe activity time is updated to reflect that activity; the client does\nnot need to specify the ``last_active_ago`` field. You cannot set the\npresence state of another user.",
"operationId": "setPresence",
"parameters": [
{
"description": "The user whose presence state to update.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The updated presence state.",
"in": "body",
"name": "presenceState",
"required": true,
"schema": {
"example": {
"presence": "online",
"status_msg": "I am here."
},
"properties": {
"presence": {
"description": "The new presence state.",
"enum": [
"online",
"offline",
"unavailable"
],
"type": "string"
},
"status_msg": {
"description": "The status message to attach to this state.",
"type": "string"
}
},
"required": [
"presence"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The new presence state was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Update this user's presence state.",
"tags": [
"Presence"
]
}
},
"/_matrix/client/r0/profile/{userId}": {
"get": {
"description": "Get the combined profile information for this user. This API may be used\nto fetch the user's own profile information or other users; either\nlocally or on remote homeservers. This API may return keys which are not\nlimited to ``displayname`` or ``avatar_url``.",
"operationId": "getUserProfile",
"parameters": [
{
"description": "The user whose profile information to get.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
}
],
"responses": {
"200": {
"description": "The avatar URL for this user.",
"examples": {
"application/json": {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid"
}
},
"schema": {
"properties": {
"avatar_url": {
"description": "The user's avatar URL if they have set one, otherwise not present.",
"type": "string"
},
"displayname": {
"description": "The user's display name if they have set one, otherwise not present.",
"type": "string"
}
},
"type": "object"
}
},
"404": {
"description": "There is no profile information for this user or this user does not exist."
}
},
"summary": "Get this user's profile information.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/profile/{userId}/avatar_url": {
"get": {
"description": "Get the user's avatar URL. This API may be used to fetch the user's\nown avatar URL or to query the URL of other users; either locally or\non remote homeservers.",
"operationId": "getAvatarUrl",
"parameters": [
{
"description": "The user whose avatar URL to get.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
}
],
"responses": {
"200": {
"description": "The avatar URL for this user.",
"examples": {
"application/json": {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
},
"schema": {
"properties": {
"avatar_url": {
"description": "The user's avatar URL if they have set one, otherwise not present.",
"type": "string"
}
},
"type": "object"
}
},
"404": {
"description": "There is no avatar URL for this user or this user does not exist."
}
},
"summary": "Get the user's avatar URL.",
"tags": [
"User data"
]
},
"put": {
"description": "This API sets the given user's avatar URL. You must have permission to\nset this user's avatar URL, e.g. you need to have their ``access_token``.",
"operationId": "setAvatarUrl",
"parameters": [
{
"description": "The user whose avatar URL to set.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The avatar url info.",
"in": "body",
"name": "avatar_url",
"required": true,
"schema": {
"example": {
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
},
"properties": {
"avatar_url": {
"description": "The new avatar URL for this user.",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The avatar URL was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Set the user's avatar URL.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/profile/{userId}/displayname": {
"get": {
"description": "Get the user's display name. This API may be used to fetch the user's\nown displayname or to query the name of other users; either locally or\non remote homeservers.",
"operationId": "getDisplayName",
"parameters": [
{
"description": "The user whose display name to get.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
}
],
"responses": {
"200": {
"description": "The display name for this user.",
"examples": {
"application/json": {
"displayname": "Alice Margatroid"
}
},
"schema": {
"properties": {
"displayname": {
"description": "The user's display name if they have set one, otherwise not present.",
"type": "string"
}
},
"type": "object"
}
},
"404": {
"description": "There is no display name for this user or this user does not exist."
}
},
"summary": "Get the user's display name.",
"tags": [
"User data"
]
},
"put": {
"description": "This API sets the given user's display name. You must have permission to\nset this user's display name, e.g. you need to have their ``access_token``.",
"operationId": "setDisplayName",
"parameters": [
{
"description": "The user whose display name to set.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The display name info.",
"in": "body",
"name": "displayName",
"required": true,
"schema": {
"example": {
"displayname": "Alice Margatroid"
},
"properties": {
"displayname": {
"description": "The new display name for this user.",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The display name was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Set the user's display name.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/publicRooms": {
"get": {
"description": "Lists the public rooms on the server.\n\nThis API returns paginated responses. The rooms are ordered by the number\nof joined members, with the largest rooms first.",
"operationId": "getPublicRooms",
"parameters": [
{
"description": "Limit the number of results returned.",
"in": "query",
"name": "limit",
"type": "number"
},
{
"description": "A pagination token from a previous request, allowing clients to\nget the next (or previous) batch of rooms.\nThe direction of pagination is specified solely by which token\nis supplied, rather than via an explicit flag.",
"in": "query",
"name": "since",
"type": "string"
},
{
"description": "The server to fetch the public room lists from. Defaults to the\nlocal server.",
"in": "query",
"name": "server",
"type": "string"
}
],
"responses": {
"200": {
"description": "A list of the rooms on the server.",
"examples": {
"application/json": {
"chunk": [
{
"aliases": [
"#murrays:cheese.bar"
],
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true
}
],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
},
"schema": {
"description": "A list of the rooms on the server.",
"properties": {
"chunk": {
"description": "A paginated chunk of public rooms.",
"items": {
"properties": {
"aliases": {
"description": "Aliases of the room. May be empty.",
"items": {
"type": "string"
},
"type": "array"
},
"avatar_url": {
"description": "The URL for the room's avatar, if one is set.",
"type": "string"
},
"canonical_alias": {
"description": "The canonical alias of the room, if any.",
"type": "string"
},
"guest_can_join": {
"description": "Whether guest users may join the room and participate in it.\nIf they can, they will be subject to ordinary power level\nrules like any other user.",
"type": "boolean"
},
"name": {
"description": "The name of the room, if any.",
"type": "string"
},
"num_joined_members": {
"description": "The number of members joined to the room.",
"type": "number"
},
"room_id": {
"description": "The ID of the room.",
"type": "string"
},
"topic": {
"description": "The topic of the room, if any.",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest users without joining.",
"type": "boolean"
}
},
"required": [
"room_id",
"num_joined_members",
"world_readable",
"guest_can_join"
],
"title": "PublicRoomsChunk",
"type": "object"
},
"title": "PublicRoomsChunks",
"type": "array"
},
"next_batch": {
"description": "A pagination token for the response. The absence of this token\nmeans there are no more results to fetch and the client should\nstop paginating.",
"type": "string"
},
"prev_batch": {
"description": "A pagination token that allows fetching previous results. The\nabsence of this token means there are no results before this\nbatch, i.e. this is the first batch.",
"type": "string"
},
"total_room_count_estimate": {
"description": "An estimate on the total number of public rooms, if the\nserver has an estimate.",
"type": "number"
}
},
"required": [
"chunk"
],
"type": "object"
}
}
},
"summary": "Lists the public rooms on the server.",
"tags": [
"Room discovery"
]
},
"post": {
"description": "Lists the public rooms on the server, with optional filter.\n\nThis API returns paginated responses. The rooms are ordered by the number\nof joined members, with the largest rooms first.",
"operationId": "queryPublicRooms",
"parameters": [
{
"description": "The server to fetch the public room lists from. Defaults to the\nlocal server.",
"in": "query",
"name": "server",
"type": "string"
},
{
"description": "Options for which rooms to return.",
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"filter": {
"generic_search_term": "foo"
},
"limit": 10
},
"properties": {
"filter": {
"description": "Filter to apply to the results.",
"properties": {
"generic_search_term": {
"description": "A string to search for in the room metadata, e.g. name,\ntopic, canonical alias etc. (Optional).",
"type": "string"
}
},
"title": "Filter",
"type": "object"
},
"limit": {
"description": "Limit the number of results returned.",
"type": "number"
},
"since": {
"description": "A pagination token from a previous request, allowing clients\nto get the next (or previous) batch of rooms. The direction\nof pagination is specified solely by which token is supplied,\nrather than via an explicit flag.",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "A list of the rooms on the server.",
"examples": {
"application/json": {
"chunk": [
{
"aliases": [
"#murrays:cheese.bar"
],
"avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
"guest_can_join": false,
"name": "CHEESE",
"num_joined_members": 37,
"room_id": "!ol19s:bleecker.street",
"topic": "Tasty tasty cheese",
"world_readable": true
}
],
"next_batch": "p190q",
"prev_batch": "p1902",
"total_room_count_estimate": 115
}
},
"schema": {
"description": "A list of the rooms on the server.",
"properties": {
"chunk": {
"description": "A paginated chunk of public rooms.",
"items": {
"properties": {
"aliases": {
"description": "Aliases of the room. May be empty.",
"items": {
"type": "string"
},
"type": "array"
},
"avatar_url": {
"description": "The URL for the room's avatar, if one is set.",
"type": "string"
},
"canonical_alias": {
"description": "The canonical alias of the room, if any.",
"type": "string"
},
"guest_can_join": {
"description": "Whether guest users may join the room and participate in it.\nIf they can, they will be subject to ordinary power level\nrules like any other user.",
"type": "boolean"
},
"name": {
"description": "The name of the room, if any.",
"type": "string"
},
"num_joined_members": {
"description": "The number of members joined to the room.",
"type": "number"
},
"room_id": {
"description": "The ID of the room.",
"type": "string"
},
"topic": {
"description": "The topic of the room, if any.",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest users without joining.",
"type": "boolean"
}
},
"required": [
"room_id",
"num_joined_members",
"world_readable",
"guest_can_join"
],
"title": "PublicRoomsChunk",
"type": "object"
},
"title": "PublicRoomsChunks",
"type": "array"
},
"next_batch": {
"description": "A pagination token for the response. The absence of this token\nmeans there are no more results to fetch and the client should\nstop paginating.",
"type": "string"
},
"prev_batch": {
"description": "A pagination token that allows fetching previous results. The\nabsence of this token means there are no results before this\nbatch, i.e. this is the first batch.",
"type": "string"
},
"total_room_count_estimate": {
"description": "An estimate on the total number of public rooms, if the\nserver has an estimate.",
"type": "number"
}
},
"required": [
"chunk"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Lists the public rooms on the server with optional filter.",
"tags": [
"Room discovery"
]
}
},
"/_matrix/client/r0/pushers": {
"get": {
"description": "Gets all currently active pushers for the authenticated user",
"operationId": "getPushers",
"responses": {
"200": {
"description": "The pushers for this user",
"examples": {
"application/json": {
"pushers": [
{
"app_display_name": "Appy McAppface",
"app_id": "face.mcapp.appy.prod",
"data": {
"url": "https://example.com/_matrix/push/v1/notify"
},
"device_display_name": "Alice's Phone",
"kind": "http",
"lang": "en-US",
"profile_tag": "xyz",
"pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A="
}
]
}
},
"schema": {
"properties": {
"pushers": {
"description": "An array containing the current pushers for the user",
"items": {
"properties": {
"app_display_name": {
"description": "A string that will allow the user to identify what application\nowns this pusher.",
"type": "string"
},
"app_id": {
"description": "This is a reverse-DNS style identifier for the application.\nMax length, 64 chars.",
"type": "string"
},
"data": {
"description": "A dictionary of information for the pusher implementation\nitself.",
"properties": {
"url": {
"description": "Required if ``kind`` is ``http``. The URL to use to send\nnotifications to.",
"type": "string"
}
},
"title": "PusherData",
"type": "object"
},
"device_display_name": {
"description": "A string that will allow the user to identify what device owns\nthis pusher.",
"type": "string"
},
"kind": {
"description": "The kind of pusher. ``\"http\"`` is a pusher that\nsends HTTP pokes.",
"type": "string"
},
"lang": {
"description": "The preferred language for receiving notifications (e.g. 'en'\nor 'en-US')",
"type": "string"
},
"profile_tag": {
"description": "This string determines which set of device specific rules this\npusher executes.",
"type": "string"
},
"pushkey": {
"description": "This is a unique identifier for this pusher. See `/set` for\nmore detail.\nMax length, 512 bytes.",
"type": "string"
}
},
"title": "Pusher",
"type": "object"
},
"title": "Pushers",
"type": "array"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets the current pushers for the authenticated user",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/pushers/set": {
"post": {
"description": "This endpoint allows the creation, modification and deletion of `pushers`_\nfor this user ID. The behaviour of this endpoint varies depending on the\nvalues in the JSON body.",
"operationId": "postPusher",
"parameters": [
{
"description": "The pusher information",
"in": "body",
"name": "pusher",
"required": true,
"schema": {
"example": {
"app_display_name": "Mat Rix",
"app_id": "com.example.app.ios",
"append": false,
"data": {
"url": "https://push-gateway.location.here"
},
"device_display_name": "iPhone 9",
"kind": "http",
"lang": "en",
"profile_tag": "xxyyzz",
"pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ"
},
"properties": {
"app_display_name": {
"description": "A string that will allow the user to identify what application\nowns this pusher.",
"type": "string"
},
"app_id": {
"description": "This is a reverse-DNS style identifier for the application.\nIt is recommended that this end with the platform, such that\ndifferent platform versions get different app identifiers.\nMax length, 64 chars.",
"type": "string"
},
"append": {
"description": "If true, the homeserver should add another pusher with the\ngiven pushkey and App ID in addition to any others with\ndifferent user IDs. Otherwise, the homeserver must remove any\nother pushers with the same App ID and pushkey for different\nusers. The default is ``false``.",
"type": "boolean"
},
"data": {
"description": "A dictionary of information for the pusher implementation\nitself. If ``kind`` is ``http``, this should contain ``url``\nwhich is the URL to use to send notifications to.",
"properties": {
"url": {
"description": "Required if ``kind`` is ``http``. The URL to use to send\nnotifications to.",
"type": "string"
}
},
"title": "PusherData",
"type": "object"
},
"device_display_name": {
"description": "A string that will allow the user to identify what device owns\nthis pusher.",
"type": "string"
},
"kind": {
"description": "The kind of pusher to configure. ``\"http\"`` makes a pusher that\nsends HTTP pokes. ``null`` deletes the pusher.",
"type": "string"
},
"lang": {
"description": "The preferred language for receiving notifications (e.g. 'en'\nor 'en-US')",
"type": "string"
},
"profile_tag": {
"description": "This string determines which set of device specific rules this\npusher executes.",
"type": "string"
},
"pushkey": {
"description": "This is a unique identifier for this pusher. The value you\nshould use for this is the routing or destination address\ninformation for the notification, for example, the APNS token\nfor APNS or the Registration ID for GCM. If your notification\nclient has no such concept, use any unique identifier.\nMax length, 512 bytes.",
"type": "string"
}
},
"required": [
"kind",
"app_id",
"app_display_name",
"device_display_name",
"pushkey",
"lang",
"data"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The pusher was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"400": {
"description": "One or more of the pusher values were invalid.",
"examples": {
"application/json": {
"errcode": "M_MISSING_PARAM",
"error": "Missing parameters: lang, data"
}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Modify a pusher for this user on the homeserver.",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/pushrules/": {
"get": {
"description": "Retrieve all push rulesets for this user. Clients can \"drill-down\" on\nthe rulesets by suffixing a ``scope`` to this path e.g.\n``/pushrules/global/``. This will return a subset of this data under the\nspecified key e.g. the ``global`` key.",
"operationId": "getPushRules",
"responses": {
"200": {
"description": "All the push rulesets for this user.",
"examples": {
"application/json": {
"global": {
"content": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"default": true,
"enabled": true,
"pattern": "alice",
"rule_id": ".m.rule.contains_user_name"
}
],
"override": [
{
"actions": [
"dont_notify"
],
"conditions": [],
"default": true,
"enabled": false,
"rule_id": ".m.rule.master"
},
{
"actions": [
"dont_notify"
],
"conditions": [
{
"key": "content.msgtype",
"kind": "event_match",
"pattern": "m.notice"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.suppress_notices"
}
],
"room": [],
"sender": [],
"underride": [
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "ring"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.call.invite"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.call"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight"
}
],
"conditions": [
{
"kind": "contains_display_name"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.contains_display_name"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"is": "2",
"kind": "room_member_count"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.room_one_to_one"
},
{
"actions": [
"notify",
{
"set_tweak": "sound",
"value": "default"
},
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.member"
},
{
"key": "content.membership",
"kind": "event_match",
"pattern": "invite"
},
{
"key": "state_key",
"kind": "event_match",
"pattern": "@alice:example.com"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.invite_for_me"
},
{
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.member"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.member_event"
},
{
"actions": [
"notify",
{
"set_tweak": "highlight",
"value": false
}
],
"conditions": [
{
"key": "type",
"kind": "event_match",
"pattern": "m.room.message"
}
],
"default": true,
"enabled": true,
"rule_id": ".m.rule.message"
}
]
}
}
},
"schema": {
"properties": {
"global": {
"allOf": [
{
"properties": {
"content": {
"items": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"title": "PushRule",
"type": "object"
},
"type": "array"
},
"override": {
"items": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"title": "PushRule",
"type": "object"
},
"type": "array"
},
"room": {
"items": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"title": "PushRule",
"type": "object"
},
"type": "array"
},
"sender": {
"items": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"title": "PushRule",
"type": "object"
},
"type": "array"
},
"underride": {
"items": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"title": "PushRule",
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The global ruleset.",
"title": "Ruleset",
"type": "object"
}
},
"required": [
"global"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Retrieve all push rulesets.",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}": {
"delete": {
"description": "This endpoint removes the push rule defined in the path.",
"operationId": "deletePushRule",
"parameters": [
{
"description": "``global`` to specify global rules.",
"in": "path",
"name": "scope",
"required": true,
"type": "string",
"x-example": "global"
},
{
"description": "The kind of rule\n",
"enum": [
"override",
"underride",
"sender",
"room",
"content"
],
"in": "path",
"name": "kind",
"required": true,
"type": "string",
"x-example": "content"
},
{
"description": "The identifier for the rule.\n",
"in": "path",
"name": "ruleId",
"required": true,
"type": "string",
"x-example": "nocake"
}
],
"responses": {
"200": {
"description": "The push rule was deleted.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Delete a push rule.",
"tags": [
"Push notifications"
]
},
"get": {
"description": "Retrieve a single specified push rule.",
"operationId": "getPushRule",
"parameters": [
{
"description": "``global`` to specify global rules.",
"in": "path",
"name": "scope",
"required": true,
"type": "string",
"x-example": "global"
},
{
"description": "The kind of rule\n",
"enum": [
"override",
"underride",
"sender",
"room",
"content"
],
"in": "path",
"name": "kind",
"required": true,
"type": "string",
"x-example": "content"
},
{
"description": "The identifier for the rule.\n",
"in": "path",
"name": "ruleId",
"required": true,
"type": "string",
"x-example": "nocake"
}
],
"responses": {
"200": {
"description": "The specific push rule. This will also include keys specific to the\nrule itself such as the rule's ``actions`` and ``conditions`` if set.",
"examples": {
"application/json": {
"actions": [
"dont_notify"
],
"default": false,
"enabled": true,
"pattern": "cake*lie",
"rule_id": "nocake"
}
},
"schema": {
"allOf": [
{
"properties": {
"actions": {
"description": "The actions to perform when this rule is matched.",
"items": {
"type": [
"object",
"string"
]
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a rule to be\napplied to an event. A rule with no conditions always matches. Only\napplicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
]
},
"type": "array"
},
"default": {
"description": "Whether this is a default rule, or has been set explicitly.",
"type": "boolean"
},
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
},
"pattern": {
"description": "The glob-style pattern to match against. Only applicable to ``content``\nrules.",
"type": "string"
},
"rule_id": {
"description": "The ID of this rule.",
"type": "string"
}
},
"required": [
"actions",
"default",
"enabled",
"rule_id"
],
"title": "PushRule",
"type": "object"
}
],
"description": "The push rule.",
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Retrieve a push rule.",
"tags": [
"Push notifications"
]
},
"put": {
"description": "This endpoint allows the creation, modification and deletion of pushers\nfor this user ID. The behaviour of this endpoint varies depending on the\nvalues in the JSON body.",
"operationId": "setPushRule",
"parameters": [
{
"description": "``global`` to specify global rules.",
"in": "path",
"name": "scope",
"required": true,
"type": "string",
"x-example": "global"
},
{
"description": "The kind of rule\n",
"enum": [
"override",
"underride",
"sender",
"room",
"content"
],
"in": "path",
"name": "kind",
"required": true,
"type": "string",
"x-example": "content"
},
{
"description": "The identifier for the rule.\n",
"in": "path",
"name": "ruleId",
"required": true,
"type": "string",
"x-example": "nocake"
},
{
"description": "Use 'before' with a ``rule_id`` as its value to make the new rule the\nnext-most important rule with respect to the given user defined rule.\nIt is not possible to add a rule relative to a predefined server rule.",
"in": "query",
"name": "before",
"required": false,
"type": "string",
"x-example": "someRuleId"
},
{
"description": "This makes the new rule the next-less important rule relative to the\ngiven user defined rule. It is not possible to add a rule relative\nto a predefined server rule.",
"in": "query",
"name": "after",
"required": false,
"type": "string",
"x-example": "anotherRuleId"
},
{
"description": "The push rule data. Additional top-level keys may be present depending\non the parameters for the rule ``kind``.",
"in": "body",
"name": "pushrule",
"required": true,
"schema": {
"example": {
"actions": [
"notify"
],
"pattern": "cake*lie"
},
"properties": {
"actions": {
"description": "The action(s) to perform when the conditions for this rule are met.",
"items": {
"enum": [
"notify",
"dont_notify",
"coalesce",
"set_tweak"
],
"type": "string"
},
"type": "array"
},
"conditions": {
"description": "The conditions that must hold true for an event in order for a\nrule to be applied to an event. A rule with no conditions\nalways matches. Only applicable to ``underride`` and ``override`` rules.",
"items": {
"allOf": [
{
"properties": {
"is": {
"description": "Required for ``room_member_count`` conditions. A decimal integer\noptionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches\nrooms where the member count is strictly less than the given number and\nso forth. If no prefix is present, this parameter defaults to ==.",
"type": "string"
},
"key": {
"description": "Required for ``event_match`` conditions. The dot-separated field of the\nevent to match.",
"type": "string",
"x-example": "content.body"
},
"kind": {
"enum": [
"event_match",
"contains_display_name",
"room_member_count"
],
"type": "string"
},
"pattern": {
"description": "Required for ``event_match`` conditions. The glob-style pattern to\nmatch against. Patterns with no special glob characters should be\ntreated as having asterisks prepended and appended when testing the\ncondition.",
"type": "string"
}
},
"required": [
"kind"
],
"title": "PushCondition",
"type": "object"
}
],
"type": "object"
},
"type": "array"
},
"pattern": {
"description": "Only applicable to ``content`` rules. The glob-style pattern to match against.",
"type": "string"
}
},
"required": [
"actions"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The pusher was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"400": {
"description": "There was a problem configuring this push rule.",
"examples": {
"application/json": {
"errcode": "M_UNKNOWN",
"error": "before/after rule not found: someRuleId"
}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Add or change a push rule.",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions": {
"put": {
"description": "This endpoint allows clients to change the actions of a push rule.\nThis can be used to change the actions of builtin rules.",
"operationId": "setPushRuleActions",
"parameters": [
{
"description": "``global`` to specify global rules.",
"in": "path",
"name": "scope",
"required": true,
"type": "string",
"x-example": "global"
},
{
"description": "The kind of rule\n",
"enum": [
"override",
"underride",
"sender",
"room",
"content"
],
"in": "path",
"name": "kind",
"required": true,
"type": "string",
"x-example": "room"
},
{
"description": "The identifier for the rule.\n",
"in": "path",
"name": "ruleId",
"required": true,
"type": "string",
"x-example": "#spam:example.com"
},
{
"description": "The action(s) to perform when the conditions for this rule are met.\n",
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"actions": [
"notify"
]
},
"properties": {
"actions": {
"description": "The action(s) to perform for this rule.",
"items": {
"enum": [
"notify",
"dont_notify",
"coalesce",
"set_tweak"
],
"type": "string"
},
"type": "array"
}
},
"required": [
"actions"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The actions for the push rule were set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Set the actions for a push rule.",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/enabled": {
"put": {
"description": "This endpoint allows clients to enable or disable the specified push rule.",
"operationId": "setPushRuleEnabled",
"parameters": [
{
"description": "``global`` to specify global rules.",
"in": "path",
"name": "scope",
"required": true,
"type": "string",
"x-example": "global"
},
{
"description": "The kind of rule\n",
"enum": [
"override",
"underride",
"sender",
"room",
"content"
],
"in": "path",
"name": "kind",
"required": true,
"type": "string",
"x-example": "content"
},
{
"description": "The identifier for the rule.\n",
"in": "path",
"name": "ruleId",
"required": true,
"type": "string",
"x-example": "nocake"
},
{
"description": "Whether the push rule is enabled or not.\n",
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"enabled": true
},
"properties": {
"enabled": {
"description": "Whether the push rule is enabled or not.",
"type": "boolean"
}
},
"required": [
"enabled"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The push rule was enabled or disabled.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Enable or disable a push rule.",
"tags": [
"Push notifications"
]
}
},
"/_matrix/client/r0/register": {
"post": {
"description": "This API endpoint uses the `User-Interactive Authentication API`_.\n\nRegister for an account on this homeserver.\n\nThere are two kinds of user account:\n\n- `user` accounts. These accounts may use the full API described in this specification.\n\n- `guest` accounts. These accounts may have limited permissions and may not be supported by all servers.\n\nIf registration is successful, this endpoint will issue an access token\nthe client can use to authorize itself in subsequent requests.\n\nIf the client does not supply a ``device_id``, the server must\nauto-generate one.\n\nThe server SHOULD register an account with a User ID based on the\n``username`` provided, if any. Note that the grammar of Matrix User ID\nlocalparts is restricted, so the server MUST either map the provided\n``username`` onto a ``user_id`` in a logical manner, or reject\n``username``\\s which do not comply to the grammar, with\n``M_INVALID_USERNAME``.\n\nMatrix clients MUST NOT assume that localpart of the registered\n``user_id`` matches the provided ``username``.\n\nThe returned access token must be associated with the ``device_id``\nsupplied by the client or generated by the server. The server may\ninvalidate any access token previously associated with that device. See\n`Relationship between access tokens and devices`_.",
"operationId": "register",
"parameters": [
{
"default": "user",
"description": "The kind of account to register. Defaults to `user`.",
"enum": [
"guest",
"user"
],
"in": "query",
"name": "kind",
"required": false,
"type": "string",
"x-example": "user"
},
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"auth": {
"additionalProperties": {
"description": "Keys dependent on the login type",
"type": "object"
},
"description": "Additional authentication information for the\nuser-interactive authentication API. Note that this\ninformation is *not* used to define how the registered user\nshould be authenticated, but is instead used to\nauthenticate the ``register`` call itself. It should be\nleft empty, or omitted, unless an earlier call returned an\nresponse with status code 401.",
"example": {
"example_credential": "verypoorsharedsecret",
"session": "xxxxx",
"type": "example.type.foo"
},
"properties": {
"session": {
"description": "The value of the session key given by the homeserver.",
"type": "string"
},
"type": {
"description": "The login type that the client is attempting to complete.",
"type": "string"
}
},
"required": [
"type"
],
"title": "Authentication Data",
"type": "object"
},
"bind_email": {
"description": "If true, the server binds the email used for authentication to\nthe Matrix ID with the ID Server.",
"example": false,
"type": "boolean"
},
"device_id": {
"description": "ID of the client device. If this does not correspond to a\nknown client device, a new device will be created. The server\nwill auto-generate a device_id if this is not specified.",
"example": "GHTYAJCE",
"type": "string"
},
"initial_device_display_name": {
"description": "A display name to assign to the newly-created device. Ignored\nif ``device_id`` corresponds to a known device.",
"example": "Jungle Phone",
"type": "string"
},
"password": {
"description": "The desired password for the account.",
"example": "ilovebananas",
"type": "string"
},
"username": {
"description": "The basis for the localpart of the desired Matrix ID. If omitted,\nthe homeserver MUST generate a Matrix ID local part.",
"example": "cheeky_monkey",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The account has been registered.",
"examples": {
"application/json": {
"access_token": "abc123",
"device_id": "GHTYAJCE",
"user_id": "@cheeky_monkey:matrix.org"
}
},
"schema": {
"properties": {
"access_token": {
"description": "An access token for the account.\nThis access token can then be used to authorize other requests.",
"type": "string"
},
"device_id": {
"description": "ID of the registered device. Will be the same as the\ncorresponding parameter in the request, if one was specified.",
"type": "string"
},
"home_server": {
"description": "The server_name of the homeserver on which the account has\nbeen registered.\n\n**Deprecated**. Clients should extract the server_name from\n``user_id`` (by splitting at the first colon) if they require\nit. Note also that ``homeserver`` is not spelt this way.",
"type": "string"
},
"user_id": {
"description": "The fully-qualified Matrix user ID (MXID) that has been registered.\n\nAny user ID returned by this API must conform to the grammar given in the\n`Matrix specification <https://matrix.org/docs/spec/appendices.html#user-identifiers>`_.",
"type": "string"
}
},
"type": "object"
}
},
"400": {
"description": "Part of the request was invalid. This may include one of the following error codes:\n\n* ``M_USER_IN_USE`` : The desired user ID is already taken.\n* ``M_INVALID_USERNAME`` : The desired user ID is not a valid user name.\n* ``M_EXCLUSIVE`` : The desired user ID is in the exclusive namespace\n claimed by an application service.\n\nThese errors may be returned at any stage of the registration process,\nincluding after authentication if the requested user ID was registered\nwhilst the client was performing authentication.\n\nHomeservers MUST perform the relevant checks and return these codes before\nperforming User-Interactive Authentication, although they may also return\nthem after authentication is completed if, for example, the requested user ID\nwas registered whilst the client was performing authentication.",
"examples": {
"application/json": {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
}
},
"401": {
"description": "The homeserver requires additional authentication information.",
"schema": {
"description": "Used by servers to indicate that additional authentication information is required,",
"properties": {
"completed": {
"description": "A list of the stages the client has completed successfully",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
},
"flows": {
"description": "A list of the login flows supported by the server for this API.",
"items": {
"properties": {
"stages": {
"description": "The login type of each of the stages required to complete this\nauthentication flow",
"items": {
"example": "example.type.foo",
"type": "string"
},
"type": "array"
}
},
"required": [
"stages"
],
"type": "object"
},
"title": "Flow information",
"type": "array"
},
"params": {
"additionalProperties": {
"type": "object"
},
"description": "Contains any information that the client will need to know in order to\nuse a given type of authentication. For each login type presented,\nthat type may be present as a key in this dictionary. For example, the\npublic part of an OAuth client ID could be given here.",
"example": {
"example.type.baz": {
"example_key": "foobar"
}
},
"type": "object"
},
"session": {
"description": "This is a session identifier that the client must pass back to the home\nserver, if one is provided, in subsequent attempts to authenticate in the\nsame API call.",
"example": "xxxxxxyz",
"type": "string"
}
},
"required": [
"flows"
],
"title": "Authentication response",
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Register for an account on this homeserver.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/register/available": {
"get": {
"description": "Checks to see if a username is available, and valid, for the server.\n\nThe server should check to ensure that, at the time of the request, the\nusername requested is available for use. This includes verifying that an\napplication service has not claimed the username and that the username\nfits the server's desired requirements (for example, a server could dictate\nthat it does not permit usernames with underscores).\n\nMatrix clients may wish to use this API prior to attempting registration,\nhowever the clients must also be aware that using this API does not normally\nreserve the username. This can mean that the username becomes unavailable\nbetween checking its availability and attempting to register it.",
"operationId": "checkUsernameAvailability",
"parameters": [
{
"default": "my_cool_localpart",
"description": "The username to check the availability of.",
"in": "query",
"name": "username",
"required": true,
"type": "string",
"x-example": "my_cool_localpart"
}
],
"responses": {
"200": {
"description": "The username is available",
"examples": {
"application/json": {
"available": true
}
},
"schema": {
"properties": {
"available": {
"description": "A flag to indicate that the username is available. This should always\nbe ``true`` when the server replies with 200 OK.",
"type": "boolean"
}
},
"type": "object"
}
},
"400": {
"description": "Part of the request was invalid or the username is not available. This may \ninclude one of the following error codes:\n\n* ``M_USER_IN_USE`` : The desired username is already taken.\n* ``M_INVALID_USERNAME`` : The desired username is not a valid user name.\n* ``M_EXCLUSIVE`` : The desired username is in the exclusive namespace\n claimed by an application service.",
"examples": {
"application/json": {
"errcode": "M_USER_IN_USE",
"error": "Desired user ID is already taken."
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Checks to see if a username is available on the server.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/ban": {
"post": {
"description": "Ban a user in the room. If the user is currently in the room, also kick them.\n\nWhen a user is banned from a room, they may not join it or be invited to it until they are unbanned.\n\nThe caller must have the required power level in order to perform this operation.",
"operationId": "ban",
"parameters": [
{
"description": "The room identifier (not alias) from which the user should be banned.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!e42d8c:matrix.org"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
},
"properties": {
"reason": {
"description": "The reason the user has been banned.",
"type": "string"
},
"user_id": {
"description": "The fully qualified user ID of the user being banned.",
"type": "string"
}
},
"required": [
"user_id"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been kicked and banned from the room.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to ban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:\n\n- The banner is not currently in the room.\n- The banner's power level is insufficient to ban users from the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to ban from this room."
}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Ban a user in the room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/context/{eventId}": {
"get": {
"description": "This API returns a number of events that happened just before and\nafter the specified event. This allows clients to get the context\nsurrounding an event.",
"operationId": "getEventContext",
"parameters": [
{
"description": "The room to get events from.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The event to get context around.",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "$f3h4d129462ha:example.com"
},
{
"description": "The maximum number of events to return. Default: 10.",
"in": "query",
"name": "limit",
"type": "integer",
"x-example": 3
}
],
"responses": {
"200": {
"description": "The events and state surrounding the requested event.",
"examples": {
"application/json": {
"end": "t29-57_2_0_2",
"events_after": [
{
"age": 91911336,
"content": {
"body": "7",
"msgtype": "m.text"
},
"event_id": "$14460306086CiUaL:localhost:8480",
"origin_server_ts": 1446030608551,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"sender": "@test:localhost:8480",
"type": "m.room.message"
}
],
"events_before": [
{
"age": 91911903,
"content": {
"body": "5",
"msgtype": "m.text"
},
"event_id": "$14460306074UYTlh:localhost:8480",
"origin_server_ts": 1446030607984,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"sender": "@test:localhost:8480",
"type": "m.room.message"
}
],
"start": "t27-54_2_0_2",
"state": [
{
"age": 3123715284,
"content": {
"creator": "@test:localhost:8480"
},
"event_id": "$14429988040dgQAE:localhost:8480",
"origin_server_ts": 1442998804603,
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"sender": "@test:localhost:8480",
"state_key": "",
"type": "m.room.create"
},
{
"age": 2067105053,
"content": {
"avatar_url": "mxc://localhost:8480/tVWZTAIIfqtXMZZtmGCkVjTD#auto",
"displayname": "Bob2",
"membership": "join"
},
"event_id": "$14440554144URDbf:localhost:8480",
"origin_server_ts": 1444055414834,
"replaces_state": "$14440552472PgiGk:localhost:8480",
"room_id": "!sCDvXTtzjpiPxaqkkt:localhost:8480",
"sender": "@test:localhost:8480",
"state_key": "@test:localhost:8480",
"type": "m.room.member"
}
]
}
},
"schema": {
"description": "The events and state surrounding the requested event.",
"properties": {
"end": {
"description": "A token that can be used to paginate forwards with.",
"type": "string"
},
"event": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "Details of the requested event."
},
"events_after": {
"description": "A list of room events that happened just after the\nrequested event, in chronological order.",
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
]
},
"type": "array"
},
"events_before": {
"description": "A list of room events that happened just before the\nrequested event, in reverse-chronological order.",
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
]
},
"type": "array"
},
"start": {
"description": "A token that can be used to paginate backwards with.",
"type": "string"
},
"state": {
"description": "The state of the room at the last event returned.",
"items": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
]
},
"type": "array"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get events and state around the specified event.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/event/{eventId}": {
"get": {
"description": "Get a single event based on ``roomId/eventId``. You must have permission to\nretrieve this event e.g. by being a member in the room for this event.",
"operationId": "getOneRoomEvent",
"parameters": [
{
"description": "The ID of the room the event is in.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!asfDuShaf7Gafaw:matrix.org"
},
{
"description": "The event ID to get.",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "$asfDuShaf7Gafaw:matrix.org"
}
],
"responses": {
"200": {
"description": "The full event.",
"examples": {
"application/json": {
"content": {
"body": "Hello world!",
"msgtype": "m.text"
},
"event_id": "$asfDuShaf7Gafaw:matrix.org",
"room_id": "!wfgy43Sg4a:matrix.org",
"sender": "@bob:matrix.org",
"type": "m.room.message"
}
},
"schema": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
]
}
},
"404": {
"description": "The event was not found or you do not have permission to read this event."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get a single event by event ID.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/forget": {
"post": {
"description": "This API stops a user remembering about a particular room.\n\nIn general, history is a first class citizen in Matrix. After this API\nis called, however, a user will no longer be able to retrieve history\nfor this room. If all users on a homeserver forget a room, the room is\neligible for deletion from that homeserver.\n\nIf the user is currently joined to the room, they will implicitly leave\nthe room as part of this API call.",
"operationId": "forgetRoom",
"parameters": [
{
"description": "The room identifier to forget.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!au1ba7o:matrix.org"
}
],
"responses": {
"200": {
"description": "The room has been forgotten.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Stop the requesting user remembering about a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/initialSync": {
"get": {
"deprecated": true,
"description": "Get a copy of the current state and the most recent messages in a room.\n\nThis endpoint was deprecated in r0 of this specification. There is no\ndirect replacement; the relevant information is returned by the\n|/sync|_ API. See the `migration guide\n<https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints>`_.",
"operationId": "roomInitialSync",
"parameters": [
{
"description": "The room to get the data.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
}
],
"responses": {
"200": {
"description": "The current state of the room",
"examples": {
"application/json": {
"account_data": [
{
"content": {
"tags": {
"work": {
"order": "1"
}
}
},
"type": "m.tag"
}
],
"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",
"sender": "@alice:example.com",
"type": "m.room.message"
},
{
"age": 343511809,
"content": {
"body": "bar",
"msgtype": "m.text"
},
"event_id": "$14328044872spjFg:example.com",
"origin_server_ts": 1432804487480,
"room_id": "!636q39766251:example.com",
"sender": "@bob:example.com",
"type": "m.room.message"
}
],
"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",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.join_rules"
},
{
"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",
"sender": "@alice:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.create"
},
{
"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",
"sender": "@bob:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member"
},
{
"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",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.power_levels"
}
],
"visibility": "private"
}
},
"schema": {
"properties": {
"account_data": {
"description": "The private data that this user has attached to this room.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"membership": {
"description": "The user's membership state in this room.",
"enum": [
"invite",
"join",
"leave",
"ban"
],
"type": "string"
},
"messages": {
"description": "The pagination chunk for this room.",
"properties": {
"chunk": {
"description": "If the user is a member of the room this will be a\nlist of the most recent messages for this room. If\nthe user has left the room this will be the\nmessages that preceeded them leaving. This array\nwill consist of at most ``limit`` elements.",
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"title": "RoomEvent",
"type": "object"
},
"type": "array"
},
"end": {
"description": "A token which correlates to the last value in ``chunk``.\nUsed for pagination.",
"type": "string"
},
"start": {
"description": "A token which correlates to the first value in ``chunk``.\nUsed for pagination.",
"type": "string"
}
},
"required": [
"start",
"end",
"chunk"
],
"title": "PaginationChunk",
"type": "object"
},
"room_id": {
"description": "The ID of this room.",
"type": "string"
},
"state": {
"description": "If the user is a member of the room this will be the\ncurrent state of the room as a list of events. If the\nuser has left the room this will be the state of the\nroom when they left it.",
"items": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
],
"title": "StateEvent",
"type": "object"
},
"type": "array"
},
"visibility": {
"description": "Whether this room is visible to the ``/publicRooms`` API\nor not.\"",
"enum": [
"private",
"public"
],
"type": "string"
}
},
"required": [
"room_id"
],
"title": "RoomInfo",
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room and weren't previously a member of the room.\n"
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Snapshot the current state of a room and its most recent messages.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/invite": {
"post": {
"description": ".. _invite-by-third-party-id-endpoint:\n\n*Note that there are two forms of this API, which are documented separately.\nThis version of the API does not require that the inviter know the Matrix\nidentifier of the invitee, and instead relies on third party identifiers.\nThe homeserver uses an identity server to perform the mapping from\nthird party identifier to a Matrix identifier. The other is documented in the*\n`joining rooms section`_.\n\nThis API invites a user to participate in a particular room.\nThey do not start participating in the room until they actually join the\nroom.\n\nOnly users currently in a particular room can invite other users to\njoin that room.\n\nIf the identity server did know the Matrix user identifier for the\nthird party identifier, the homeserver will append a ``m.room.member``\nevent to the room.\n\nIf the identity server does not know a Matrix user identifier for the\npassed third party identifier, the homeserver will issue an invitation\nwhich can be accepted upon providing proof of ownership of the third\nparty identifier. This is achieved by the identity server generating a\ntoken, which it gives to the inviting homeserver. The homeserver will\nadd an ``m.room.third_party_invite`` event into the graph for the room,\ncontaining that token.\n\nWhen the invitee binds the invited third party identifier to a Matrix\nuser ID, the identity server will give the user a list of pending\ninvitations, each containing:\n\n- The room ID to which they were invited\n\n- The token given to the homeserver\n\n- A signature of the token, signed with the identity server's private key\n\n- The matrix user ID who invited them to the room\n\nIf a token is requested from the identity server, the homeserver will\nappend a ``m.room.third_party_invite`` event to the room.\n\n.. _joining rooms section: `invite-by-user-id-endpoint`_",
"operationId": "inviteBy3PID",
"parameters": [
{
"description": "The room identifier (not alias) to which to invite the user.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!d41d8cd:matrix.org"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"address": "cheeky@monkey.com",
"id_server": "matrix.org",
"medium": "email"
},
"properties": {
"address": {
"description": "The invitee's third party identifier.",
"type": "string"
},
"id_server": {
"description": "The hostname+port of the identity server which should be used for third party identifier lookups.",
"type": "string"
},
"medium": {
"description": "The kind of address being passed in the address field, for example ``email``.",
"type": "string"
}
},
"required": [
"id_server",
"medium",
"address"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been invited to join the room.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:\n\n- The invitee has been banned from the room.\n- The invitee is already a member of the room.\n- The inviter is not currently in the room.\n- The inviter's power level is insufficient to invite users to the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Invite a user to participate in a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/invite ": {
"post": {
"description": ".. _invite-by-user-id-endpoint:\n\n*Note that there are two forms of this API, which are documented separately.\nThis version of the API requires that the inviter knows the Matrix\nidentifier of the invitee. The other is documented in the*\n`third party invites section`_.\n\nThis API invites a user to participate in a particular room.\nThey do not start participating in the room until they actually join the\nroom.\n\nOnly users currently in a particular room can invite other users to\njoin that room.\n\nIf the user was invited to the room, the homeserver will append a\n``m.room.member`` event to the room.\n\n.. _third party invites section: `invite-by-third-party-id-endpoint`_",
"operationId": "inviteUser",
"parameters": [
{
"description": "The room identifier (not alias) to which to invite the user.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!d41d8cd:matrix.org"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"user_id": "@cheeky_monkey:matrix.org"
},
"properties": {
"user_id": {
"description": "The fully qualified user ID of the invitee.",
"type": "string"
}
},
"required": [
"user_id"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been invited to join the room.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to invite the user to the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:\n\n- The invitee has been banned from the room.\n- The invitee is already a member of the room.\n- The inviter is not currently in the room.\n- The inviter's power level is insufficient to invite users to the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "@cheeky_monkey:matrix.org is banned from the room"
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Invite a user to participate in a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/join": {
"post": {
"description": "*Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*\n\nThis API starts a user participating in a particular room, if that user\nis allowed to participate in that room. After this call, the client is\nallowed to see all current state events in the room, and all subsequent\nevents associated with the room until the user leaves the room.\n\nAfter a user has joined a room, the room will appear as an entry in the\nresponse of the |/initialSync|_ and |/sync|_ APIs.\n\nIf a ``third_party_signed`` was supplied, the homeserver must verify\nthat it matches a pending ``m.room.third_party_invite`` event in the\nroom, and perform key validity checking if required by the event.",
"operationId": "joinRoomById",
"parameters": [
{
"description": "The room identifier (not alias) to join.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!d41d8cd:matrix.org"
},
{
"in": "body",
"name": "third_party_signed",
"schema": {
"example": {
"third_party_signed": {
"mxid": "@green:eggs.ham",
"sender": "@cat:the.hat",
"signatures": {
"horton.hears": {
"ed25519:0": "some9signature"
}
},
"token": "random8nonce"
}
},
"properties": {
"third_party_signed": {
"description": "A signature of an ``m.third_party_invite`` token to prove that this user owns a third party identity which has been invited to the room.",
"properties": {
"mxid": {
"description": "The Matrix ID of the invitee.",
"type": "string"
},
"sender": {
"description": "The Matrix ID of the user who issued the invite.",
"type": "string"
},
"signatures": {
"description": "A signatures object containing a signature of the entire signed object.",
"title": "Signatures",
"type": "object"
},
"token": {
"description": "The state key of the m.third_party_invite event.",
"type": "string"
}
},
"required": [
"sender",
"mxid",
"token",
"signatures"
],
"title": "ThirdPartySigned",
"type": "object"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The room has been joined.\n\nThe joined room ID must be returned in the ``room_id`` field.",
"examples": {
"application/json": {
"room_id": "!d41d8cd:matrix.org"
}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to join the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejection are:\n\n- The room is invite-only and the user was not invited.\n- The user has been banned from the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "You are not invited to this room."
}
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Start the requesting user participating in a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/joined_members": {
"get": {
"description": "This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.",
"operationId": "getJoinedMembersByRoom",
"parameters": [
{
"description": "The room to get the members of.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
}
],
"responses": {
"200": {
"description": "A map of MXID to room member objects.",
"examples": {
"application/json": {
"joined": {
"@bar:example.com": {
"avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK",
"display_name": "Bar"
}
}
}
},
"schema": {
"properties": {
"joined": {
"additionalProperties": {
"properties": {
"avatar_url": {
"description": "The mxc avatar url of the user this object is representing.",
"type": "string"
},
"display_name": {
"description": "The display name of the user this object is representing.",
"type": "string"
}
},
"title": "RoomMember",
"type": "object"
},
"description": "A map from user ID to a RoomMember object.",
"type": "object"
}
},
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room.\n"
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Gets the list of currently joined users and their profile data.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/kick": {
"post": {
"description": "Kick a user from the room.\n\nThe caller must have the required power level in order to perform this operation.",
"operationId": "kick",
"parameters": [
{
"description": "The room identifier (not alias) from which the user should be kicked.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!e42d8c:matrix.org"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"reason": "Telling unfunny jokes",
"user_id": "@cheeky_monkey:matrix.org"
},
"properties": {
"reason": {
"description": "The reason the user has been kicked.",
"type": "string"
},
"user_id": {
"description": "The fully qualified user ID of the user being kicked.",
"type": "string"
}
},
"required": [
"user_id"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been kicked from the room.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to kick the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:\n\n- The kicker is not currently in the room.\n- The kickee is not currently in the room.\n- The kicker's power level is insufficient to kick users from the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to kick from this room."
}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Kick a user from the room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/leave": {
"post": {
"description": "This API stops a user participating in a particular room.\n\nIf the user was already in the room, they will no longer be able to see\nnew events in the room. If the room requires an invite to join, they\nwill need to be re-invited before they can re-join.\n\nIf the user was invited to the room, but had not joined, this call\nserves to reject the invite.\n\nThe user will still be allowed to retrieve history from the room which\nthey were previously allowed to see.",
"operationId": "leaveRoom",
"parameters": [
{
"description": "The room identifier to leave.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!nkl290a:matrix.org"
}
],
"responses": {
"200": {
"description": "The room has been left.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Stop the requesting user participating in a particular room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/members": {
"get": {
"description": "Get the list of members for this room.",
"operationId": "getMembersByRoom",
"parameters": [
{
"description": "The room to get the member events for.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
}
],
"responses": {
"200": {
"description": "A list of members of the room. If you are joined to the room then\nthis will be the current members of the room. If you have left the\nroom then this will be the members of the room when you left.",
"examples": {
"application/json": {
"chunk": [
{
"age": 6547561012,
"content": {
"avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
"membership": "join"
},
"event_id": "$1426600438280zExKY:example.com",
"membership": "join",
"origin_server_ts": 1426600438277,
"room_id": "!636q39766251:example.com",
"sender": "@alice:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member"
},
{
"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",
"sender": "@bob:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member"
}
]
}
},
"schema": {
"properties": {
"chunk": {
"items": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
],
"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.\n\nThe following membership states are specified:\n\n- ``invite`` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.\n\n- ``join`` - The user has joined the room (possibly after accepting an invite), and may participate in it.\n\n- ``leave`` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).\n\n- ``ban`` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ``ban``).\n\n- ``knock`` - This is a reserved word, which currently has no meaning.\n\nThe ``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.\n\nThis 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 subset of state events such as the room name.",
"properties": {
"content": {
"properties": {
"avatar_url": {
"description": "The avatar URL for this user, if any. This is added by the homeserver.",
"type": "string"
},
"displayname": {
"description": "The display name for this user, if any. This is added by the homeserver.",
"type": [
"string",
"null"
]
},
"is_direct": {
"description": "Flag indicating if the room containing this event was created with the intention of being a direct chat. See `Direct Messaging`_.",
"type": "boolean"
},
"membership": {
"description": "The membership state of the user.",
"enum": [
"invite",
"join",
"knock",
"leave",
"ban"
],
"type": "string"
},
"third_party_invite": {
"properties": {
"display_name": {
"description": "A name which can be displayed to represent the user instead of their third party identifier",
"type": "string"
},
"signed": {
"description": "A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.",
"properties": {
"mxid": {
"description": "The invited matrix user ID. Must be equal to the user_id property of the event.",
"type": "string"
},
"signatures": {
"description": "A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.",
"title": "Signatures",
"type": "object"
},
"token": {
"description": "The token property of the containing third_party_invite object.",
"type": "string"
}
},
"required": [
"mxid",
"signatures",
"token"
],
"title": "signed",
"type": "object"
}
},
"required": [
"display_name",
"signed"
],
"title": "Invite",
"type": "object"
}
},
"required": [
"membership"
],
"title": "EventContent",
"type": "object"
},
"invite_room_state": {
"description": "A subset of the state of the room at the time of the invite, if ``membership`` is ``invite``. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for ``m.room.avatar``, ``m.room.canonical_alias``, ``m.room.join_rules``, and ``m.room.name`` SHOULD be included.",
"items": {
"description": "A stripped down state event, with only the ``type``, ``state_key`` and ``content`` keys.",
"properties": {
"content": {
"description": "The ``content`` for the event.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "The ``state_key`` for the event.",
"type": "string"
},
"type": {
"description": "The ``type`` for the event.",
"type": "string"
}
},
"required": [
"type",
"state_key",
"content"
],
"title": "StrippedState",
"type": "object"
},
"type": "array"
},
"state_key": {
"description": "The ``user_id`` this membership event relates to.",
"type": "string"
},
"type": {
"enum": [
"m.room.member"
],
"type": "string"
}
},
"title": "The current membership state of a user in the room.",
"type": "object"
}
],
"title": "MemberEvent",
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room and weren't previously a member of the room.\n"
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get the m.room.member events for the room.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/messages": {
"get": {
"description": "This API returns a list of message and state events for a room. It uses\npagination query parameters to paginate history in the room.",
"operationId": "getRoomEvents",
"parameters": [
{
"description": "The room to get events from.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The token to start returning events from. This token can be obtained\nfrom a ``prev_batch`` token returned for each room by the sync API,\nor from a ``start`` or ``end`` token returned by a previous request\nto this endpoint.",
"in": "query",
"name": "from",
"required": true,
"type": "string",
"x-example": "s345_678_333"
},
{
"description": "The token to stop returning events at. This token can be obtained from\na ``prev_batch`` token returned for each room by the sync endpoint,\nor from a ``start`` or ``end`` token returned by a previous request to\nthis endpoint.",
"in": "query",
"name": "to",
"required": false,
"type": "string"
},
{
"description": "The direction to return events from.",
"enum": [
"b",
"f"
],
"in": "query",
"name": "dir",
"required": true,
"type": "string",
"x-example": "b"
},
{
"description": "The maximum number of events to return. Default: 10.",
"in": "query",
"name": "limit",
"type": "integer",
"x-example": "3"
},
{
"description": "A JSON RoomEventFilter to filter returned events with.",
"in": "query",
"name": "filter",
"type": "string",
"x-example": "{\"contains_url\":true}"
}
],
"responses": {
"200": {
"description": "A list of messages with a new token to request more.",
"examples": {
"application/json": {
"chunk": [
{
"age": 1042,
"content": {
"body": "hello world",
"msgtype": "m.text"
},
"event_id": "$1444812213350496Caaaa:example.com",
"origin_server_ts": 1444812213737,
"room_id": "!Xq3620DUiqCaoxq:example.com",
"sender": "@alice:example.com",
"type": "m.room.message"
},
{
"age": 20123,
"content": {
"body": "the world is big",
"msgtype": "m.text"
},
"event_id": "$1444812213350496Cbbbb:example.com",
"origin_server_ts": 1444812194656,
"room_id": "!Xq3620DUiqCaoxq:example.com",
"sender": "@bob:example.com",
"type": "m.room.message"
},
{
"age": 50789,
"content": {
"name": "New room name"
},
"event_id": "$1444812213350496Ccccc:example.com",
"origin_server_ts": 1444812163990,
"prev_content": {
"name": "Old room name"
},
"room_id": "!Xq3620DUiqCaoxq:example.com",
"sender": "@bob:example.com",
"state_key": "",
"type": "m.room.name"
}
],
"end": "t47409-4357353_219380_26003_2265",
"start": "t47429-4392820_219380_26003_2265"
}
},
"schema": {
"description": "A list of messages with a new token to request more.",
"properties": {
"chunk": {
"description": "A list of room events.",
"items": {
"title": "RoomEvent",
"type": "object"
},
"type": "array"
},
"end": {
"description": "The token the pagination ends at. If ``dir=b`` this token should\nbe used again to request even earlier events.",
"type": "string"
},
"start": {
"description": "The token the pagination starts from. If ``dir=b`` this will be\nthe token supplied in ``from``.",
"type": "string"
}
},
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room.\n"
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get a list of events for this room",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/receipt/{receiptType}/{eventId}": {
"post": {
"description": "This API updates the marker for the given receipt type to the event ID\nspecified.",
"operationId": "postReceipt",
"parameters": [
{
"description": "The room in which to send the event.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!wefuh21ffskfuh345:example.com"
},
{
"description": "The type of receipt to send.",
"enum": [
"m.read"
],
"in": "path",
"name": "receiptType",
"required": true,
"type": "string",
"x-example": "m.read"
},
{
"description": "The event ID to acknowledge up to.",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "$1924376522eioj:example.com"
},
{
"description": "Extra receipt information to attach to ``content`` if any. The\nserver will automatically set the ``ts`` field.",
"in": "body",
"name": "receipt",
"schema": {
"example": {},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The receipt was sent.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Send a receipt for the given event ID.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/redact/{eventId}/{txnId}": {
"put": {
"description": "Strips all information out of an event which isn't critical to the\nintegrity of the server-side representation of the room.\n\nThis cannot be undone.\n\nUsers may redact their own events, and any user with a power level\ngreater than or equal to the `redact` power level of the room may\nredact events there.",
"operationId": "redactEvent",
"parameters": [
{
"description": "The room from which to redact the event.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!637q39766251:example.com"
},
{
"description": "The ID of the event to redact",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "bai2b1i9:matrix.org"
},
{
"description": "The transaction ID for this event. Clients should generate a\nunique ID; it will be used by the server to ensure idempotency of requests.",
"in": "path",
"name": "txnId",
"required": true,
"type": "string",
"x-example": "37"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"reason": "Indecent material"
},
"properties": {
"reason": {
"description": "The reason for the event being redacted.",
"type": "string"
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "An ID for the redaction event.",
"examples": {
"application/json": {
"event_id": "$YUwQidLecu:example.com"
}
},
"schema": {
"properties": {
"event_id": {
"description": "A unique identifier for the event.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Strips all non-integrity-critical information out of an event.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/report/{eventId}": {
"post": {
"description": "Reports an event as inappropriate to the server, which may then notify\nthe appropriate people.",
"operationId": "reportContent",
"parameters": [
{
"description": "The room in which the event being reported is located.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!637q39766251:example.com"
},
{
"description": "The event to report.",
"in": "path",
"name": "eventId",
"required": true,
"type": "string",
"x-example": "$something:domain.com"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"reason": "this makes me sad",
"score": -100
},
"properties": {
"reason": {
"description": "The reason the content is being reported. May be blank.",
"type": "string"
},
"score": {
"description": "The score to rate this content as where -100 is most offensive\nand 0 is inoffensive.",
"type": "integer"
}
},
"required": [
"score",
"reason"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The event has been reported successfully.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Reports an event as inappropriate.",
"tags": [
"Reporting content"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}": {
"put": {
"description": "This endpoint is used to send a message event to a room. Message events\nallow access to historical events and pagination, making them suited\nfor \"once-off\" activity in a room.\n\nThe body of the request should be the content object of the event; the\nfields in this object will vary depending on the type of event. See\n`Room Events`_ for the m. event specification.",
"operationId": "sendMessage",
"parameters": [
{
"description": "The room to send the event to.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The type of event to send.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.room.message"
},
{
"description": "The transaction ID for this event. Clients should generate an\nID unique across requests with the same access token; it will be\nused by the server to ensure idempotency of requests.",
"in": "path",
"name": "txnId",
"required": true,
"type": "string",
"x-example": "35"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"body": "hello",
"msgtype": "m.text"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "An ID for the sent event.",
"examples": {
"application/json": {
"event_id": "$YUwRidLecu:example.com"
}
},
"schema": {
"properties": {
"event_id": {
"description": "A unique identifier for the event.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Send a message event to the given room.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/state": {
"get": {
"description": "Get the state events for the current state of a room.",
"operationId": "getRoomState",
"parameters": [
{
"description": "The room to look up the state for.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
}
],
"responses": {
"200": {
"description": "The current state of the room",
"examples": {
"application/json": [
{
"age": 7148266897,
"content": {
"join_rule": "public"
},
"event_id": "$14259997323TLwtb:example.com",
"origin_server_ts": 1425999732392,
"room_id": "!636q39766251:example.com",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.join_rules"
},
{
"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",
"sender": "@alice:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member"
},
{
"age": 7148267200,
"content": {
"creator": "@alice:example.com"
},
"event_id": "$14259997320KhbwJ:example.com",
"origin_server_ts": 1425999732089,
"room_id": "!636q39766251:example.com",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.create"
},
{
"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",
"sender": "@bob:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member"
},
{
"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",
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.power_levels"
}
]
},
"schema": {
"description": "If the user is a member of the room this will be the\ncurrent state of the room as a list of events. If the user\nhas left the room then this will be the state of the room\nwhen they left as a list of events.",
"items": {
"allOf": [
{
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
}
],
"title": "StateEvent",
"type": "object"
},
"title": "RoomState",
"type": "array"
}
},
"403": {
"description": "You aren't a member of the room and weren't previously a member of the room.\n"
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get all state events in the current state of a room.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/state/{eventType}": {
"get": {
"description": "Looks up the contents of a state event in a room. If the user is\njoined to the room then the state is taken from the current\nstate of the room. If the user has left the room then the state is\ntaken from the state of the room when they left.\n\nThis looks up the state event with the empty state key.",
"operationId": "getRoomStateByType",
"parameters": [
{
"description": "The room to look up the state in.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The type of state to look up.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.room.name"
}
],
"responses": {
"200": {
"description": "The content of the state event.",
"examples": {
"application/json": {
"name": "Example room name"
}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room and weren't previously a member of the room.\n"
},
"404": {
"description": "The room has no state with the given type or key."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get the state identified by the type, with the empty state key.",
"tags": [
"Room participation"
]
},
"put": {
"description": "State events can be sent using this endpoint. This endpoint is\nequivalent to calling `/rooms/{roomId}/state/{eventType}/{stateKey}`\nwith an empty `stateKey`. Previous state events with matching\n`<roomId>` and `<eventType>`, and empty `<stateKey>`, will be overwritten.\n\nRequests to this endpoint **cannot use transaction IDs**\nlike other ``PUT`` paths because they cannot be differentiated from the\n``state_key``. Furthermore, ``POST`` is unsupported on state paths.\n\nThe body of the request should be the content object of the event; the\nfields in this object will vary depending on the type of event. See\n`Room Events`_ for the ``m.`` event specification.\n",
"operationId": "setRoomState",
"parameters": [
{
"description": "The room to set the state in",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The type of event to send.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.room.name"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"name": "New name for the room"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "An ID for the sent event.",
"examples": {
"application/json": {
"event_id": "$YUwRidLecu:example.com"
}
},
"schema": {
"properties": {
"event_id": {
"description": "A unique identifier for the event.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Send a state event to the given room.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}": {
"get": {
"description": "Looks up the contents of a state event in a room. If the user is\njoined to the room then the state is taken from the current\nstate of the room. If the user has left the room then the state is\ntaken from the state of the room when they left.",
"operationId": "getRoomStateWithKey",
"parameters": [
{
"description": "The room to look up the state in.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The type of state to look up.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.room.name"
},
{
"description": "The key of the state to look up.",
"in": "path",
"name": "stateKey",
"required": true,
"type": "string",
"x-example": ""
}
],
"responses": {
"200": {
"description": "The content of the state event.",
"examples": {
"application/json": {
"name": "Example room name"
}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You aren't a member of the room and weren't previously a member of the room.\n"
},
"404": {
"description": "The room has no state with the given type or key."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get the state identified by the type and key.",
"tags": [
"Room participation"
]
},
"put": {
"description": "State events can be sent using this endpoint. These events will be\noverwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all\nmatch.\n\nRequests to this endpoint **cannot use transaction IDs**\nlike other ``PUT`` paths because they cannot be differentiated from the\n``state_key``. Furthermore, ``POST`` is unsupported on state paths.\n\nThe body of the request should be the content object of the event; the\nfields in this object will vary depending on the type of event. See\n`Room Events`_ for the ``m.`` event specification.\n",
"operationId": "setRoomStateWithKey",
"parameters": [
{
"description": "The room to set the state in",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!636q39766251:example.com"
},
{
"description": "The type of event to send.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.room.member"
},
{
"description": "The state_key for the state to send. Defaults to the empty string.",
"in": "path",
"name": "stateKey",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
"displayname": "Alice Margatroid",
"membership": "join"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "An ID for the sent event.",
"examples": {
"application/json": {
"event_id": "$YUwRidLecu:example.com"
}
},
"schema": {
"properties": {
"event_id": {
"description": "A unique identifier for the event.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Send a state event to the given room.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/typing/{userId}": {
"put": {
"description": "This tells the server that the user is typing for the next N\nmilliseconds where N is the value specified in the ``timeout`` key.\nAlternatively, if ``typing`` is ``false``, it tells the server that the\nuser has stopped typing.",
"operationId": "setTyping",
"parameters": [
{
"description": "The user who has started to type.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The room in which the user is typing.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!wefh3sfukhs:example.com"
},
{
"description": "The current typing state.",
"in": "body",
"name": "typingState",
"required": true,
"schema": {
"example": {
"timeout": 30000,
"typing": true
},
"properties": {
"timeout": {
"description": "The length of time in milliseconds to mark this user as typing.",
"type": "integer"
},
"typing": {
"description": "Whether the user is typing or not. If ``false``, the ``timeout``\nkey can be omitted.",
"type": "boolean"
}
},
"required": [
"typing"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The new typing state was set.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Informs the server that the user has started or stopped typing.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/rooms/{roomId}/unban": {
"post": {
"description": "Unban a user from the room. This allows them to be invited to the room,\nand join if they would otherwise be allowed to join according to its join rules.\n\nThe caller must have the required power level in order to perform this operation.",
"operationId": "unban",
"parameters": [
{
"description": "The room identifier (not alias) from which the user should be unbanned.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!e42d8c:matrix.org"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"user_id": "@cheeky_monkey:matrix.org"
},
"properties": {
"user_id": {
"description": "The fully qualified user ID of the user being unbanned.",
"type": "string"
}
},
"required": [
"user_id"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The user has been unbanned from the room.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
},
"403": {
"description": "You do not have permission to unban the user from the room. A meaningful ``errcode`` and description error text will be returned. Example reasons for rejections are:\n\n- The unbanner's power level is insufficient to unban users from the room.",
"examples": {
"application/json": {
"errcode": "M_FORBIDDEN",
"error": "You do not have a high enough power level to unban from this room."
}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Unban a user from the room.",
"tags": [
"Room membership"
]
}
},
"/_matrix/client/r0/search": {
"post": {
"description": "Performs a full text search across different categories.",
"operationId": "search",
"parameters": [
{
"description": "The point to return events from. If given, this should be a\n`next_batch` result from a previous call to this endpoint.",
"in": "query",
"name": "next_batch",
"type": "string",
"x-example": "YWxsCgpOb25lLDM1ODcwOA"
},
{
"in": "body",
"name": "body",
"schema": {
"example": {
"search_categories": {
"room_events": {
"groupings": {
"group_by": [
{
"key": "room_id"
}
]
},
"keys": [
"content.body"
],
"order_by": "recent",
"search_term": "martians and men"
}
}
},
"properties": {
"search_categories": {
"description": "Describes which categories to search in and their criteria.",
"properties": {
"room_events": {
"description": "Mapping of category name to search criteria.",
"properties": {
"event_context": {
"description": "Configures whether any context for the events\nreturned are included in the response.",
"properties": {
"after_limit": {
"description": "How many events after the result are\nreturned. By default, this is ``5``.",
"title": "After limit",
"type": "integer"
},
"before_limit": {
"description": "How many events before the result are\nreturned. By default, this is ``5``.",
"title": "Before limit",
"type": "integer"
},
"include_profile": {
"description": "Requests that the server returns the\nhistoric profile information for the users\nthat sent the events that were returned.\nBy default, this is ``false``.",
"title": "Return profile information",
"type": "boolean"
}
},
"title": "Event Context",
"type": "object"
},
"filter": {
"description": "This takes a `filter`_.",
"title": "Filter",
"type": "object"
},
"groupings": {
"description": "Requests that the server partitions the result set\nbased on the provided list of keys.",
"properties": {
"group_by": {
"description": "List of groups to request.",
"items": {
"description": "Configuration for group.",
"properties": {
"key": {
"description": "Key that defines the group.",
"enum": [
"room_id",
"sender"
],
"title": "Group Key",
"type": "string"
}
},
"title": "Group",
"type": "object"
},
"title": "Groups",
"type": "array"
}
},
"title": "Groupings",
"type": "object"
},
"include_state": {
"description": "Requests the server return the current state for\neach room returned.",
"title": "Include current state",
"type": "boolean"
},
"keys": {
"description": "The keys to search. Defaults to all.",
"items": {
"enum": [
"content.body",
"content.name",
"content.topic"
],
"type": "string"
},
"type": "array"
},
"order_by": {
"description": "The order in which to search for results.\nBy default, this is ``\"rank\"``.",
"enum": [
"recent",
"rank"
],
"title": "Ordering",
"type": "string"
},
"search_term": {
"description": "The string to search events for",
"type": "string"
}
},
"required": [
"search_term"
],
"title": "Room Events",
"type": "object"
}
},
"title": "Categories",
"type": "object"
}
},
"required": [
"search_categories"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "Results of the search.",
"examples": {
"application/json": {
"search_categories": {
"room_events": {
"count": 1224,
"groups": {
"room_id": {
"!qPewotXpIctQySfjSy:localhost": {
"next_batch": "BdgFsdfHSf-dsFD",
"order": 1,
"results": [
"$144429830826TWwbB:localhost"
]
}
}
},
"highlights": [
"martians",
"men"
],
"next_batch": "5FdgFsd234dfgsdfFD",
"results": [
{
"rank": 0.00424866,
"result": {
"age": 526228296,
"content": {
"body": "Test content martians and men",
"msgtype": "m.text"
},
"event_id": "$144429830826TWwbB:localhost",
"origin_server_ts": 1444298308034,
"room_id": "!qPewotXpIctQySfjSy:localhost",
"sender": "@test:localhost",
"type": "m.room.message"
}
}
]
}
}
}
},
"schema": {
"properties": {
"search_categories": {
"description": "Describes which categories to search in and their criteria.",
"properties": {
"room_events": {
"description": "Mapping of category name to search criteria.",
"properties": {
"count": {
"description": "An approximate count of the total number of results found.",
"type": "number"
},
"groups": {
"additionalProperties": {
"additionalProperties": {
"description": "The results for a particular group value.",
"properties": {
"next_batch": {
"description": "Token that can be used to get the next batch\nof results in the group, by passing as the\n`next_batch` parameter to the next call. If\nthis field is absent, there are no more\nresults in this group.",
"title": "Next Batch in Group",
"type": "string"
},
"order": {
"description": "Key that can be used to order different\ngroups.",
"title": "Group Order",
"type": "integer"
},
"results": {
"description": "Which results are in this group.",
"items": {
"title": "Result Event ID",
"type": "string"
},
"type": "array"
}
},
"title": "Group Value",
"type": "object"
},
"description": "The results for a given group.",
"title": "Group Key",
"type": "object"
},
"description": "Any groups that were requested.",
"title": "Groups",
"type": "object"
},
"highlights": {
"description": "List of words which should be highlighted, useful for stemming which may change the query terms.",
"items": {
"type": "string"
},
"title": "Highlights",
"type": "array"
},
"next_batch": {
"description": "Token that can be used to get the next batch of\nresults, by passing as the `next_batch` parameter to\nthe next call. If this field is absent, there are no\nmore results.",
"title": "Next Batch",
"type": "string"
},
"results": {
"description": "List of results in the requested order.",
"items": {
"description": "The result object.",
"properties": {
"context": {
"description": "Context for result, if requested.",
"properties": {
"end": {
"description": "Pagination token for the end of the chunk",
"title": "End Token",
"type": "string"
},
"events_after": {
"description": "Events just after the result.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Event",
"type": "object"
},
"title": "Events After",
"type": "array"
},
"events_before": {
"description": "Events just before the result.",
"items": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Event",
"type": "object"
},
"title": "Events Before",
"type": "array"
},
"profile_info": {
"additionalProperties": {
"properties": {
"avatar_url": {
"title": "Avatar Url",
"type": "string"
},
"displayname": {
"title": "Display name",
"type": "string"
}
},
"title": "User Profile",
"type": "object"
},
"description": "The historic profile information of the\nusers that sent the events returned.",
"title": "Profile Information",
"type": "object"
},
"start": {
"description": "Pagination token for the start of the chunk",
"title": "Start Token",
"type": "string"
}
},
"title": "Event Context",
"type": "object"
},
"rank": {
"description": "A number that describes how closely this result matches the search. Higher is closer.",
"type": "number"
},
"result": {
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "The event that matched.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Event",
"type": "object"
}
},
"title": "Result",
"type": "object"
},
"title": "Results",
"type": "array"
},
"state": {
"additionalProperties": {
"items": {
"allOf": [
{
"allOf": [
{
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type"
],
"title": "Event",
"type": "object"
}
],
"description": "In addition to the Event fields, Room Events have the following additional fields.",
"properties": {
"event_id": {
"description": "The globally unique event identifier.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"type": "number"
},
"room_id": {
"description": "The ID of the room associated with this event.",
"type": "string"
},
"sender": {
"description": "Contains the fully-qualified ID of the user who *sent* this event.",
"type": "string"
},
"unsigned": {
"description": "Contains optional extra information about the event.",
"properties": {
"age": {
"description": "The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.",
"type": "integer"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "The client-supplied transaction ID, if the client being given the event is the same one which sent it.",
"type": "string"
}
},
"title": "UnsignedData",
"type": "object"
}
},
"required": [
"event_id",
"room_id",
"sender",
"origin_server_ts"
],
"title": "Room Event",
"type": "object"
}
],
"description": "In addition to the Room Event fields, State Events have the following additional fields.",
"properties": {
"prev_content": {
"description": "Optional. The previous ``content`` for this event. If there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"state_key": {
"description": "A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.",
"type": "string"
}
},
"required": [
"state_key"
],
"title": "State Event",
"type": "object"
},
"title": "Room State",
"type": "array"
},
"description": "The current state for every room in the results.\nThis is included if the request had the\n``include_state`` key set with a value of ``true``.",
"title": "Current state",
"type": "object"
}
},
"title": "Room Event Results",
"type": "object"
}
},
"title": "Categories",
"type": "object"
}
},
"required": [
"search_categories"
],
"title": "Results",
"type": "object"
}
},
"400": {
"description": "Part of the request was invalid."
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Perform a server-side search.",
"tags": [
"Search"
]
}
},
"/_matrix/client/r0/sendToDevice/{eventType}/{txnId}": {
"put": {
"description": "This endpoint is used to send send-to-device events to a set of\nclient devices.",
"operationId": "sendToDevice",
"parameters": [
{
"description": "The type of event to send.",
"in": "path",
"name": "eventType",
"required": true,
"type": "string",
"x-example": "m.new_device"
},
{
"description": "The transaction ID for this event. Clients should generate an\nID unique across requests with the same access token; it will be\nused by the server to ensure idempotency of requests.",
"in": "path",
"name": "txnId",
"required": true,
"type": "string",
"x-example": "35"
},
{
"in": "body",
"name": "body",
"required": true,
"schema": {
"properties": {
"messages": {
"additionalProperties": {
"additionalProperties": {
"description": "Message content",
"title": "EventContent",
"type": "object"
},
"type": "object"
},
"description": "The messages to send. A map from user ID, to a map from\ndevice ID to message body. The device ID may also be `*`,\nmeaning all known devices for the user.",
"example": {
"@alice:example.com": {
"TLLBEANAAG": {
"example_content_key": "value"
}
}
},
"type": "object"
}
},
"title": "body",
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The message was successfully sent.",
"examples": {
"application/json": {}
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Send an event to a given set of devices.",
"tags": [
"Send-to-Device messaging"
]
}
},
"/_matrix/client/r0/sync": {
"get": {
"description": "Synchronise the client's state with the latest state on the server.\nClients use this API when they first log in to get an initial snapshot\nof the state on the server, and then continue to call this API to get\nincremental deltas to the state, and to receive new messages.",
"operationId": "sync",
"parameters": [
{
"description": "The ID of a filter created using the filter API or a filter JSON\nobject encoded as a string. The server will detect whether it is\nan ID or a JSON object by whether the first character is a ``\"{\"``\nopen brace. Passing the JSON inline is best suited to one off\nrequests. Creating a filter using the filter API is recommended for\nclients that reuse the same filter multiple times, for example in\nlong poll requests.",
"in": "query",
"name": "filter",
"type": "string",
"x-example": "66696p746572"
},
{
"description": "A point in time to continue a sync from.",
"in": "query",
"name": "since",
"type": "string",
"x-example": "s72594_4483_1934"
},
{
"description": "Controls whether to include the full state for all rooms the user\nis a member of.\n\nIf this is set to ``true``, then all state events will be returned,\neven if ``since`` is non-empty. The timeline will still be limited\nby the ``since`` parameter. In this case, the ``timeout`` parameter\nwill be ignored and the query will return immediately, possibly with\nan empty timeline.\n\nIf ``false``, and ``since`` is non-empty, only state which has\nchanged since the point indicated by ``since`` will be returned.\n\nBy default, this is ``false``.",
"in": "query",
"name": "full_state",
"type": "boolean",
"x-example": "false"
},
{
"description": "Controls whether the client is automatically marked as online by\npolling this API. If this parameter is omitted then the client is\nautomatically marked as online when it uses this API. Otherwise if\nthe parameter is set to \"offline\" then the client is not marked as\nbeing online when it uses this API.",
"enum": [
"offline"
],
"in": "query",
"name": "set_presence",
"type": "string",
"x-example": "offline"
},
{
"description": "The maximum time to wait, in milliseconds, before returning this\nrequest. If no events (or other data) become available before this\ntime elapses, the server will return a response with empty fields.\n\nBy default, this is ``0``, so the server will return immediately\neven if the response is empty.",
"in": "query",
"name": "timeout",
"type": "integer",
"x-example": 30000
}
],
"responses": {
"200": {
"description": "The initial snapshot or delta for the client to use to update their state.",
"examples": {
"application/json": {
"account_data": {
"events": [
{
"content": {
"custom_config_key": "custom_config_value"
},
"type": "org.example.custom.config"
}
]
},
"next_batch": "s72595_4483_1934",
"presence": {
"events": [
{
"content": {
"presence": "online"
},
"sender": "@alice:example.com",
"type": "m.presence"
}
]
},
"rooms": {
"invite": {
"!696r7674:example.com": {
"invite_state": {
"events": [
{
"content": {
"name": "My Room Name"
},
"sender": "@alice:example.com",
"state_key": "",
"type": "m.room.name"
},
{
"content": {
"membership": "invite"
},
"sender": "@alice:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member"
}
]
}
}
},
"join": {
"!726s6s6q:example.com": {
"account_data": {
"events": [
{
"content": {
"tags": {
"work": {
"order": 1
}
}
},
"type": "m.tag"
},
{
"content": {
"custom_config_key": "custom_config_value"
},
"type": "org.example.custom.room.config"
}
]
},
"ephemeral": {
"events": [
{
"content": {
"user_ids": [
"@alice:example.com"
]
},
"type": "m.typing"
}
]
},
"state": {
"events": [
{
"content": {
"membership": "join"
},
"event_id": "$66697273743031:example.com",
"origin_server_ts": 1417731086795,
"sender": "@alice:example.com",
"state_key": "@alice:example.com",
"type": "m.room.member"
}
]
},
"timeline": {
"events": [
{
"content": {
"membership": "join"
},
"event_id": "$7365636s6r6432:example.com",
"origin_server_ts": 1417731086795,
"prev_content": {
"membership": "invite"
},
"sender": "@bob:example.com",
"state_key": "@bob:example.com",
"type": "m.room.member"
},
{
"age": 124524,
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"event_id": "$74686972643033:example.com",
"origin_server_ts": 1417731086797,
"sender": "@alice:example.com",
"txn_id": "1234",
"type": "m.room.message"
}
],
"limited": true,
"prev_batch": "t34-23535_0_0"
}
}
},
"leave": {}
}
}
},
"schema": {
"properties": {
"account_data": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The global private data created by this user.",
"title": "Account Data",
"type": "object"
},
"device_lists": {
"description": "Information on end-to-end device updates, as specified in\n|device_lists_sync|_.",
"title": "DeviceLists",
"type": "object"
},
"next_batch": {
"description": "The batch token to supply in the ``since`` param of the next\n``/sync`` request.",
"type": "string"
},
"presence": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The updates to the presence status of other users.",
"title": "Presence",
"type": "object"
},
"rooms": {
"description": "Updates to rooms.",
"properties": {
"invite": {
"additionalProperties": {
"properties": {
"invite_state": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The state of a room that the user has been invited\nto. These state events may only have the ``sender``,\n``type``, ``state_key`` and ``content`` keys\npresent. These events do not replace any state that\nthe client already has for the room, for example if\nthe client has archived the room. Instead the\nclient should keep two separate copies of the\nstate: the one from the ``invite_state`` and one\nfrom the archived ``state``. If the client joins\nthe room then the current state will be given as a\ndelta against the archived ``state`` not the\n``invite_state``.",
"title": "InviteState",
"type": "object"
}
},
"title": "Invited Room",
"type": "object"
},
"description": "The rooms that the user has been invited to.",
"title": "Invited Rooms",
"type": "object"
},
"join": {
"additionalProperties": {
"properties": {
"account_data": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The private data that this user has attached to\nthis room.",
"title": "Account Data",
"type": "object"
},
"ephemeral": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The ephemeral events in the room that aren't\nrecorded in the timeline or state of the room.\ne.g. typing.",
"title": "Ephemeral",
"type": "object"
},
"state": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "Updates to the state, between the time indicated by\nthe ``since`` parameter, and the start of the\n``timeline`` (or all state up to the start of the\n``timeline``, if ``since`` is not given, or\n``full_state`` is true).",
"title": "State",
"type": "object"
},
"timeline": {
"allOf": [
{
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"properties": {
"limited": {
"description": "True if the number of events returned was limited by the ``limit`` on the filter",
"type": "boolean"
},
"prev_batch": {
"description": "A token that can be supplied to the ``from`` parameter of the rooms/{roomId}/messages endpoint",
"type": "string"
}
},
"type": "object"
}
],
"description": "The timeline of messages and state changes in the\nroom.",
"title": "Timeline",
"type": "object"
},
"unread_notifications": {
"description": "Counts of unread notifications for this room",
"properties": {
"highlight_count": {
"description": "The number of unread notifications for this room with the highlight flag set",
"title": "Highlighted notification count",
"type": "integer"
},
"notification_count": {
"description": "The total number of unread notifications for this room",
"title": "Total notification count",
"type": "integer"
}
},
"title": "Unread Notification Counts",
"type": "object"
}
},
"title": "Joined Room",
"type": "object"
},
"description": "The rooms that the user has joined.",
"title": "Joined Rooms",
"type": "object"
},
"leave": {
"additionalProperties": {
"properties": {
"state": {
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"description": "The state updates for the room up to the start of the timeline.",
"title": "State",
"type": "object"
},
"timeline": {
"allOf": [
{
"allOf": [
{
"properties": {
"events": {
"description": "List of events",
"items": {
"allOf": [
{
"properties": {
"content": {
"description": "The content of this event. The fields in this object will vary depending on the type of event.",
"title": "EventContent",
"type": "object"
},
"event_id": {
"description": "The ID of this event, if applicable.",
"type": "string"
},
"origin_server_ts": {
"description": "Timestamp in milliseconds on originating homeserver when this event was sent.",
"format": "int64",
"type": "integer"
},
"sender": {
"description": "The MXID of the user who sent this event.",
"type": "string"
},
"state_key": {
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.",
"type": "string"
},
"type": {
"description": "The type of event.",
"type": "string"
},
"unsigned": {
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"description": "Time in milliseconds since the event was sent.",
"format": "int64",
"type": "integer"
},
"prev_content": {
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing.",
"title": "EventContent",
"type": "object"
},
"redacted_because": {
"description": "Optional. The event that redacted this event, if any.",
"title": "Event",
"type": "object"
},
"transaction_id": {
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.",
"type": "string"
}
},
"title": "Unsigned",
"type": "object"
}
},
"title": "Event",
"type": "object"
}
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
],
"properties": {
"limited": {
"description": "True if the number of events returned was limited by the ``limit`` on the filter",
"type": "boolean"
},
"prev_batch": {
"description": "A token that can be supplied to the ``from`` parameter of the rooms/{roomId}/messages endpoint",
"type": "string"
}
},
"type": "object"
}
],
"description": "The timeline of messages and state changes in the\nroom up to the point when the user left.",
"title": "Timeline",
"type": "object"
}
},
"title": "Left Room",
"type": "object"
},
"description": "The rooms that the user has left or been banned from.",
"title": "Left rooms",
"type": "object"
}
},
"title": "Rooms",
"type": "object"
},
"to_device": {
"description": "Information on the send-to-device messages for the client\ndevice, as defined in |send_to_device_sync|_.",
"title": "ToDevice",
"type": "object"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Synchronise the client's state and receive new messages.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/user/{userId}/account_data/{type}": {
"put": {
"description": "Set some account_data for the client. This config is only visible to the user\nthat set the account_data. The config will be synced to clients in the\ntop-level ``account_data``.",
"operationId": "setAccountData",
"parameters": [
{
"description": "The id of the user to set account_data for. The access token must be\nauthorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The event type of the account_data to set. Custom types should be\nnamespaced to avoid clashes.",
"in": "path",
"name": "type",
"required": true,
"type": "string",
"x-example": "org.example.custom.config"
},
{
"description": "The content of the account_data",
"in": "body",
"name": "content",
"required": true,
"schema": {
"example": {
"custom_account_data_key": "custom_config_value"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The account_data was successfully added."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Set some account_data for the user.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/user/{userId}/filter": {
"post": {
"description": "Uploads a new filter definition to the homeserver.\nReturns a filter ID that may be used in future requests to\nrestrict which events are returned to the client.",
"operationId": "defineFilter",
"parameters": [
{
"description": "The id of the user uploading the filter. The access token must be authorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The filter to upload.",
"in": "body",
"name": "filter",
"required": true,
"schema": {
"allOf": [
{
"properties": {
"account_data": {
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"description": "The user account data that isn't associated with rooms to include."
},
"event_fields": {
"description": "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\\\'. A server may include more fields than were requested.",
"items": {
"type": "string"
},
"type": "array"
},
"event_format": {
"description": "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
"enum": [
"client",
"federation"
],
"type": "string"
},
"presence": {
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"description": "The presence updates to include."
},
"room": {
"description": "Filters to be applied to room data.",
"properties": {
"account_data": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The per user account data to include for rooms."
},
"ephemeral": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms."
},
"include_leave": {
"description": "Include rooms that the user has left in the sync, default false",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data``",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data``",
"items": {
"type": "string"
},
"type": "array"
},
"state": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The state events to include for rooms."
},
"timeline": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The message and state update events to include for rooms."
}
},
"title": "RoomFilter",
"type": "object"
}
},
"type": "object"
}
],
"example": {
"event_fields": [
"type",
"content",
"sender"
],
"event_format": "client",
"presence": {
"not_senders": [
"@alice:example.com"
],
"types": [
"m.presence"
]
},
"room": {
"ephemeral": {
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
],
"types": [
"m.receipt",
"m.typing"
]
},
"state": {
"not_rooms": [
"!726s6s6q:example.com"
],
"types": [
"m.room.*"
]
},
"timeline": {
"limit": 10,
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
],
"types": [
"m.room.message"
]
}
}
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The filter was created.",
"examples": {
"application/json": {
"filter_id": "66696p746572"
}
},
"schema": {
"properties": {
"filter_id": {
"description": "The ID of the filter that was created.",
"type": "string"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Upload a new filter.",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/user/{userId}/filter/{filterId}": {
"get": {
"operationId": "getFilter",
"parameters": [
{
"description": "The user ID to download a filter for.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The filter ID to download.",
"in": "path",
"name": "filterId",
"required": true,
"type": "string",
"x-example": "66696p746572"
}
],
"responses": {
"200": {
"description": "\"The filter defintion\"",
"examples": {
"application/json": {
"event_fields": [
"type",
"content",
"sender"
],
"event_format": "client",
"presence": {
"not_senders": [
"@alice:example.com"
],
"types": [
"m.presence"
]
},
"room": {
"ephemeral": {
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
],
"types": [
"m.receipt",
"m.typing"
]
},
"state": {
"not_rooms": [
"!726s6s6q:example.com"
],
"types": [
"m.room.*"
]
},
"timeline": {
"limit": 10,
"not_rooms": [
"!726s6s6q:example.com"
],
"not_senders": [
"@spam:example.com"
],
"types": [
"m.room.message"
]
}
}
}
},
"schema": {
"allOf": [
{
"properties": {
"account_data": {
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"description": "The user account data that isn't associated with rooms to include."
},
"event_fields": {
"description": "List of event fields to include. If this list is absent then all fields are included. The entries may include '.' charaters to indicate sub-fields. So ['content.body'] will include the 'body' field of the 'content' object. A literal '.' character in a field name may be escaped using a '\\\\'. A server may include more fields than were requested.",
"items": {
"type": "string"
},
"type": "array"
},
"event_format": {
"description": "The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as receieved over federation. The default is 'client'.",
"enum": [
"client",
"federation"
],
"type": "string"
},
"presence": {
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"description": "The presence updates to include."
},
"room": {
"description": "Filters to be applied to room data.",
"properties": {
"account_data": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The per user account data to include for rooms."
},
"ephemeral": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The events that aren't recorded in the room history, e.g. typing and receipts, to include for rooms."
},
"include_leave": {
"description": "Include rooms that the user has left in the sync, default false",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data``",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ``ephemeral``, ``state``, ``timeline`` or ``account_data``",
"items": {
"type": "string"
},
"type": "array"
},
"state": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The state events to include for rooms."
},
"timeline": {
"allOf": [
{
"allOf": [
{
"properties": {
"limit": {
"description": "The maximum number of events to return.",
"type": "integer"
},
"not_senders": {
"description": "A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the ``'senders'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"not_types": {
"description": "A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the ``'types'`` filter. A '*' can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
},
"senders": {
"description": "A list of senders IDs to include. If this list is absent then all senders are included.",
"items": {
"type": "string"
},
"type": "array"
},
"types": {
"description": "A list of event types to include. If this list is absent then all event types are included. A ``'*'`` can be used as a wildcard to match any sequence of characters.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "Filter",
"type": "object"
}
],
"properties": {
"contains_url": {
"description": "If ``true``, includes only events with a url key in their content. If ``false``, excludes those events.",
"type": "boolean"
},
"not_rooms": {
"description": "A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the ``'rooms'`` filter.",
"items": {
"type": "string"
},
"type": "array"
},
"rooms": {
"description": "A list of room IDs to include. If this list is absent then all rooms are included.",
"items": {
"type": "string"
},
"type": "array"
}
},
"title": "RoomEventFilter",
"type": "object"
}
],
"description": "The message and state update events to include for rooms."
}
},
"title": "RoomFilter",
"type": "object"
}
},
"type": "object"
}
],
"type": "object"
}
},
"404": {
"description": "Unknown filter."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Download a filter",
"tags": [
"Room participation"
]
}
},
"/_matrix/client/r0/user/{userId}/rooms/{roomId}/account_data/{type}": {
"put": {
"description": "Set some account_data for the client on a given room. This config is only\nvisible to the user that set the account_data. The config will be synced to\nclients in the per-room ``account_data``.",
"operationId": "setAccountDataPerRoom",
"parameters": [
{
"description": "The id of the user to set account_data for. The access token must be\nauthorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The id of the room to set account_data on.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!726s6s6q:example.com"
},
{
"description": "The event type of the account_data to set. Custom types should be\nnamespaced to avoid clashes.",
"in": "path",
"name": "type",
"required": true,
"type": "string",
"x-example": "org.example.custom.room.config"
},
{
"description": "The content of the account_data",
"in": "body",
"name": "content",
"required": true,
"schema": {
"example": {
"custom_account_data_key": "custom_account_data_value"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The account_data was successfully added."
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Set some account_data for the user.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/user/{userId}/rooms/{roomId}/tags": {
"get": {
"description": "List the tags set by a user on a room.",
"operationId": "getRoomTags",
"parameters": [
{
"description": "The id of the user to get tags for. The access token must be\nauthorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The id of the room to get tags for.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!726s6s6q:example.com"
}
],
"responses": {
"200": {
"description": "The list of tags for the user for the room.",
"examples": {
"application/json": {
"tags": {
"pinned": {},
"work": {
"order": "1"
}
}
}
},
"schema": {
"properties": {
"tags": {
"title": "Tags",
"type": "object"
}
},
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "List the tags for a room.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/user/{userId}/rooms/{roomId}/tags/{tag}": {
"delete": {
"description": "Remove a tag from the room.",
"operationId": "deleteRoomTag",
"parameters": [
{
"description": "The id of the user to remove a tag for. The access token must be\nauthorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The id of the room to remove a tag from.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!726s6s6q:example.com"
},
{
"description": "The tag to remove.",
"in": "path",
"name": "tag",
"required": true,
"type": "string",
"x-example": "work"
}
],
"responses": {
"200": {
"description": "The tag was successfully removed",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Remove a tag from the room.",
"tags": [
"User data"
]
},
"put": {
"description": "Add a tag to the room.",
"operationId": "setRoomTag",
"parameters": [
{
"description": "The id of the user to add a tag for. The access token must be\nauthorized to make requests for this user id.",
"in": "path",
"name": "userId",
"required": true,
"type": "string",
"x-example": "@alice:example.com"
},
{
"description": "The id of the room to add a tag to.",
"in": "path",
"name": "roomId",
"required": true,
"type": "string",
"x-example": "!726s6s6q:example.com"
},
{
"description": "The tag to add.",
"in": "path",
"name": "tag",
"required": true,
"type": "string",
"x-example": "work"
},
{
"description": "Extra data for the tag, e.g. ordering.",
"in": "body",
"name": "body",
"required": true,
"schema": {
"example": {
"order": "1"
},
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The tag was successfully added.",
"examples": {
"application/json": {}
},
"schema": {
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Add a tag to a room.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/user_directory/search": {
"post": {
"description": "This API performs a server-side search over all users registered on the server.\nIt searches user ID and displayname case-insensitively for users that you share a room with or that are in public rooms.",
"operationId": "searchUserDirectory",
"parameters": [
{
"in": "body",
"name": "body",
"schema": {
"properties": {
"limit": {
"description": "The maximum number of results to return (Defaults to 10).",
"example": 10,
"type": "number"
},
"search_term": {
"description": "The term to search for",
"example": "foo",
"type": "string"
}
},
"required": [
"search_term"
],
"type": "object"
}
}
],
"responses": {
"200": {
"description": "The results of the search.",
"examples": {
"application/json": {
"limited": false,
"results": [
{
"avatar_url": "mxc://bar.com/foo",
"display_name": "Foo",
"user_id": "@foo:bar.com"
}
]
}
},
"schema": {
"properties": {
"limited": {
"description": "Indicates if the result list has been truncated by the limit.",
"type": "boolean"
},
"results": {
"description": "Ordered by rank and then whether or not profile info is available.",
"items": {
"properties": {
"avatar_url": {
"description": "The avatar url, as an MXC, if one exists.",
"example": "mxc://bar.com/foo",
"type": "string"
},
"display_name": {
"description": "The display name of the user, if one exists.",
"example": "Foo",
"type": "string"
},
"user_id": {
"description": "The user's matrix user ID.",
"example": "@foo:bar.com",
"type": "string"
}
},
"required": [
"user_id"
],
"title": "User",
"type": "object"
},
"type": "array"
}
},
"required": [
"results",
"limited"
],
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Searches the user directory.",
"tags": [
"User data"
]
}
},
"/_matrix/client/r0/voip/turnServer": {
"get": {
"description": "This API provides credentials for the client to use when initiating\ncalls.",
"operationId": "getTurnServer",
"responses": {
"200": {
"description": "The TURN server credentials.",
"examples": {
"application/json": {
"password": "JlKfBy1QwLrO20385QyAtEyIv0=",
"ttl": 86400,
"uris": [
"turn:turn.example.com:3478?transport=udp",
"turn:10.20.30.40:3478?transport=tcp",
"turns:10.20.30.40:443?transport=tcp"
],
"username": "1443779631:@user:example.com"
}
},
"schema": {
"properties": {
"password": {
"description": "The password to use.",
"type": "string"
},
"ttl": {
"description": "The time-to-live in seconds",
"type": "integer"
},
"uris": {
"description": "A list of TURN URIs",
"items": {
"type": "string"
},
"type": "array"
},
"username": {
"description": "The username to use.",
"type": "string"
}
},
"required": [
"username",
"password",
"uris",
"ttl"
],
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Obtain TURN server credentials.",
"tags": [
"VOIP"
]
}
},
"/_matrix/client/versions": {
"get": {
"description": "Gets the versions of the specification supported by the server.\n\nValues will take the form ``rX.Y.Z``.\n\nOnly the latest ``Z`` value will be reported for each supported ``X.Y`` value.\ni.e. if the server implements ``r0.0.0``, ``r0.0.1``, and ``r1.2.0``, it will report ``r0.0.1`` and ``r1.2.0``.",
"operationId": "getVersions",
"responses": {
"200": {
"description": "The versions supported by the server.",
"examples": {
"application/json": {
"versions": [
"r0.0.1"
]
}
},
"schema": {
"properties": {
"versions": {
"description": "The supported versions.",
"items": {
"description": "The supported versions",
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
},
"summary": "Gets the versions of the specification supported by the server.",
"tags": [
"Server administration"
]
}
},
"/_matrix/media/r0/download/{serverName}/{mediaId}": {
"get": {
"operationId": "getContent",
"parameters": [
{
"description": "The server name from the ``mxc://`` URI (the authoritory component)\n",
"in": "path",
"name": "serverName",
"required": true,
"type": "string",
"x-example": "matrix.org"
},
{
"description": "The media ID from the ``mxc://`` URI (the path component)\n",
"in": "path",
"name": "mediaId",
"required": true,
"type": "string",
"x-example": "ascERGshawAWawugaAcauga"
},
{
"description": "Indicates to the server that it should not attempt to fetch the media if it is deemed\nremote. This is to prevent routing loops where the server contacts itself. Defaults to \ntrue if not provided.\n",
"in": "query",
"name": "allow_remote",
"required": false,
"type": "boolean",
"x-example": false
}
],
"produces": [
"*/*"
],
"responses": {
"200": {
"description": "The content that was previously uploaded.",
"headers": {
"Content-Disposition": {
"description": "The name of the file that was previously uploaded, if set.",
"type": "string"
},
"Content-Type": {
"description": "The content type of the file that was previously uploaded.",
"type": "string"
}
},
"schema": {
"type": "file"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Download content from the content repository.",
"tags": [
"Media"
]
}
},
"/_matrix/media/r0/download/{serverName}/{mediaId}/{fileName}": {
"get": {
"operationId": "getContentOverrideName",
"parameters": [
{
"description": "The server name from the ``mxc://`` URI (the authoritory component)\n",
"in": "path",
"name": "serverName",
"required": true,
"type": "string",
"x-example": "matrix.org"
},
{
"description": "The media ID from the ``mxc://`` URI (the path component)\n",
"in": "path",
"name": "mediaId",
"required": true,
"type": "string",
"x-example": "ascERGshawAWawugaAcauga"
},
{
"description": "The filename to give in the Content-Disposition\n",
"in": "path",
"name": "fileName",
"required": true,
"type": "string",
"x-example": "filename.jpg"
},
{
"description": "Indicates to the server that it should not attempt to fetch the media if it is deemed\nremote. This is to prevent routing loops where the server contacts itself. Defaults to \ntrue if not provided.\n",
"in": "query",
"name": "allow_remote",
"required": false,
"type": "boolean",
"x-example": false
}
],
"produces": [
"*/*"
],
"responses": {
"200": {
"description": "The content that was previously uploaded.",
"headers": {
"Content-Disposition": {
"description": "The name of file given in the request",
"type": "string"
},
"Content-Type": {
"description": "The content type of the file that was previously uploaded.",
"type": "string"
}
},
"schema": {
"type": "file"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Download content from the content repository as a given filename.",
"tags": [
"Media"
]
}
},
"/_matrix/media/r0/preview_url": {
"get": {
"operationId": "getUrlPreview",
"parameters": [
{
"description": "The URL to get a preview of",
"in": "query",
"name": "url",
"required": true,
"type": "string",
"x-example": "https://matrix.org"
},
{
"description": "The preferred point in time to return a preview for. The server may\nreturn a newer version if it does not have the requested version\navailable.",
"in": "query",
"name": "ts",
"type": "number",
"x-example": 1510610716656
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The OpenGraph data for the URL, which may be empty. Some values are\nreplaced with matrix equivalents if they are provided in the response.\nThe differences from the OpenGraph protocol are described here.",
"examples": {
"application/json": {
"matrix:image:size": 102400,
"og:description": "This is a really cool blog post from matrix.org",
"og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
"og:image:height": 48,
"og:image:type": "image/png",
"og:image:width": 48,
"og:title": "Matrix Blog Post"
}
},
"schema": {
"properties": {
"matrix:image:size": {
"description": "The byte-size of the image. Omitted if there is no image attached.",
"type": "number"
},
"og:image": {
"description": "An MXC URI to the image. Omitted if there is no image.",
"type": "string"
}
},
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Get information about a URL for a client",
"tags": [
"Media"
]
}
},
"/_matrix/media/r0/thumbnail/{serverName}/{mediaId}": {
"get": {
"operationId": "getContentThumbnail",
"parameters": [
{
"description": "The server name from the ``mxc://`` URI (the authoritory component)\n",
"in": "path",
"name": "serverName",
"required": true,
"type": "string",
"x-example": "matrix.org"
},
{
"description": "The media ID from the ``mxc://`` URI (the path component)\n",
"in": "path",
"name": "mediaId",
"required": true,
"type": "string",
"x-example": "ascERGshawAWawugaAcauga"
},
{
"description": "The *desired* width of the thumbnail. The actual thumbnail may not\nmatch the size specified.",
"in": "query",
"name": "width",
"type": "integer",
"x-example": 64
},
{
"description": "The *desired* height of the thumbnail. The actual thumbnail may not\nmatch the size specified.",
"in": "query",
"name": "height",
"type": "integer",
"x-example": 64
},
{
"description": "The desired resizing method.",
"enum": [
"crop",
"scale"
],
"in": "query",
"name": "method",
"type": "string",
"x-example": "scale"
},
{
"description": "Indicates to the server that it should not attempt to fetch the media if it is deemed\nremote. This is to prevent routing loops where the server contacts itself. Defaults to \ntrue if not provided.\n",
"in": "query",
"name": "allow_remote",
"required": false,
"type": "boolean",
"x-example": false
}
],
"produces": [
"image/jpeg",
"image/png"
],
"responses": {
"200": {
"description": "A thumbnail of the requested content.",
"headers": {
"Content-Type": {
"description": "The content type of the thumbnail.",
"enum": [
"image/jpeg",
"image/png"
],
"type": "string"
}
},
"schema": {
"type": "file"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"summary": "Download a thumbnail of the content from the content repository.",
"tags": [
"Media"
]
}
},
"/_matrix/media/r0/upload": {
"post": {
"operationId": "uploadContent",
"parameters": [
{
"description": "The content type of the file being uploaded",
"in": "header",
"name": "Content-Type",
"type": "string",
"x-example": "Content-Type: audio/mpeg"
},
{
"description": "The name of the file being uploaded",
"in": "query",
"name": "filename",
"type": "string",
"x-example": "War and Peace.pdf"
},
{
"description": "The content to be uploaded.",
"in": "body",
"name": "<content>",
"required": true,
"schema": {
"example": "<bytes>",
"format": "byte",
"type": "string"
}
}
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The MXC URI for the uploaded content.",
"examples": {
"application/json": {
"content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
},
"schema": {
"properties": {
"content_uri": {
"description": "The MXC URI to the uploaded content.",
"type": "string"
}
},
"required": [
"content_uri"
],
"type": "object"
}
},
"429": {
"description": "This request was rate-limited.",
"schema": {
"description": "A Matrix-level Error",
"properties": {
"errcode": {
"description": "An error code.",
"type": "string"
},
"error": {
"description": "A human-readable error message.",
"type": "string"
}
},
"required": [
"errcode"
],
"type": "object"
}
}
},
"security": [
{
"accessToken": []
}
],
"summary": "Upload some content to the content repository.",
"tags": [
"Media"
]
}
}
},
"produces": [
"application/json"
],
"schemes": [
"https"
],
"securityDefinitions": {
"accessToken": {
"description": "The access_token returned by a call to ``/login`` or ``/register``",
"in": "query",
"name": "access_token",
"type": "apiKey"
}
},
"swagger": "2.0"
}
Reference in New Issue View Git Blame Copy Permalink