Skip to content

Instantly share code, notes, and snippets.

@qalqi

qalqi/synapse-swagger.json

Last active June 12, 2020 16:16
Show Gist options
  • Save qalqi/4bcfd816b026140a32d34316d5176c96 to your computer and use it in GitHub Desktop.
Save qalqi/4bcfd816b026140a32d34316d5176c96 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
synapse-swagger.json
{
"basePath" : "/",
"consumes" : [ "application/json" ],
"host" : "matrix.social.network",
"info" : {
"title" : "Matrix Client-Server API",
"version" : "r0.6.1"
},
"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" : [ {
"added_at" : 1535336848756,
"address" : "monkey@banana.island",
"medium" : "email",
"validated_at" : 1535176800000
} ]
}
},
"schema" : {
"properties" : {
"threepids" : {
"items" : {
"properties" : {
"added_at" : {
"description" : "The timestamp, in milliseconds, when the homeserver associated the third party identifier with the user.",
"format" : "int64",
"type" : "integer"
},
"address" : {
"description" : "The third party identifier address.",
"type" : "string"
},
"medium" : {
"description" : "The medium of the third party identifier.",
"enum" : [ "email", "msisdn" ],
"type" : "string"
},
"validated_at" : {
"description" : "The timestamp, in milliseconds, when the identifier was\nvalidated by the identity server.",
"format" : "int64",
"type" : "integer"
}
},
"required" : [ "medium", "address", "validated_at", "added_at" ],
"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" ]
}
},
"/_matrix/client/r0/account/3pid/bind" : {
"post" : {
"description" : "Binds a 3PID to the user's account through the specified identity server.\n\nHomeservers should not prevent this request from succeeding if another user\nhas bound the 3PID. Homeservers should simply proxy any errors received by\nthe identity server to the caller.\n\nHomeservers should track successful binds so they can be unbound later.",
"operationId" : "bind3PID",
"parameters" : [ {
"in" : "body",
"name" : "body",
"schema" : {
"example" : {
"client_secret" : "d0n'tT3ll",
"id_access_token" : "abc123_OpaqueString",
"id_server" : "example.org",
"sid" : "abc123987"
},
"properties" : {
"client_secret" : {
"description" : "The client secret used in the session with the identity server.",
"type" : "string"
},
"id_access_token" : {
"description" : "An access token previously registered 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", "id_access_token", "sid" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The addition was successful.",
"examples" : {
"application/json" : { },
"schema" : {
"type" : "object"
}
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Binds a 3PID to the user's account through an Identity Service.",
"tags" : [ "User data" ]
}
},
"/_matrix/client/r0/account/3pid/delete" : {
"post" : {
"description" : "Removes a third party identifier from the user's account. This might not\ncause an unbind of the identifier from the identity server.\n\nUnlike other endpoints, this endpoint does not take an ``id_access_token``\nparameter because the homeserver is expected to sign the request to the\nidentity server instead.",
"operationId" : "delete3pidFromAccount",
"parameters" : [ {
"in" : "body",
"name" : "body",
"schema" : {
"properties" : {
"address" : {
"description" : "The third party address being removed.",
"example" : "example@example.org",
"type" : "string"
},
"id_server" : {
"description" : "The identity server to unbind from. If not provided, the homeserver\nMUST use the ``id_server`` the identifier was added through. If the\nhomeserver does not know the original ``id_server``, it MUST return\na ``id_server_unbind_result`` of ``no-support``.",
"example" : "example.org",
"type" : "string"
},
"medium" : {
"description" : "The medium of the third party identifier being removed.",
"enum" : [ "email", "msisdn" ],
"example" : "email",
"type" : "string"
}
},
"required" : [ "medium", "address" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The homeserver has disassociated the third party identifier from the\nuser.",
"schema" : {
"properties" : {
"id_server_unbind_result" : {
"description" : "An indicator as to whether or not the homeserver was able to unbind\nthe 3PID from the identity server. ``success`` indicates that the\nindentity server has unbound the identifier whereas ``no-support``\nindicates that the identity server refuses to support the request\nor the homeserver was not able to determine an identity server to\nunbind from.",
"enum" : [ "no-support", "success" ],
"example" : "success",
"type" : "string"
}
},
"required" : [ "id_server_unbind_result" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Deletes a third party identifier from the user's account",
"tags" : [ "User data" ]
}
},
"/_matrix/client/r0/account/3pid/unbind" : {
"post" : {
"description" : "Removes a user's third party identifier from the provided identity server\nwithout removing it from the homeserver.\n\nUnlike other endpoints, this endpoint does not take an ``id_access_token``\nparameter because the homeserver is expected to sign the request to the\nidentity server instead.",
"operationId" : "unbind3pidFromAccount",
"parameters" : [ {
"in" : "body",
"name" : "body",
"schema" : {
"properties" : {
"address" : {
"description" : "The third party address being removed.",
"example" : "example@example.org",
"type" : "string"
},
"id_server" : {
"description" : "The identity server to unbind from. If not provided, the homeserver\nMUST use the ``id_server`` the identifier was added through. If the\nhomeserver does not know the original ``id_server``, it MUST return\na ``id_server_unbind_result`` of ``no-support``.",
"example" : "example.org",
"type" : "string"
},
"medium" : {
"description" : "The medium of the third party identifier being removed.",
"enum" : [ "email", "msisdn" ],
"example" : "email",
"type" : "string"
}
},
"required" : [ "medium", "address" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The identity server has disassociated the third party identifier from the\nuser.",
"schema" : {
"properties" : {
"id_server_unbind_result" : {
"description" : "An indicator as to whether or not the identity server was able to unbind\nthe 3PID. ``success`` indicates that the identity server has unbound the\nidentifier whereas ``no-support`` indicates that the identity server\nrefuses to support the request or the homeserver was not able to determine\nan identity server to unbind from.",
"enum" : [ "no-support", "success" ],
"example" : "success",
"type" : "string"
}
},
"required" : [ "id_server_unbind_result" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Removes a user's third party identifier from an identity server.",
"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.\n\nUnlike other endpoints, this endpoint does not take an ``id_access_token``\nparameter because the homeserver is expected to sign the request to the\nidentity server instead.",
"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"
},
"id_server" : {
"description" : "The identity server to unbind all of the user's 3PIDs from.\nIf not provided, the homeserver MUST use the ``id_server``\nthat was originally use to bind each identifier. If the\nhomeserver does not know which ``id_server`` that was,\nit must return an ``id_server_unbind_result`` of\n``no-support``.",
"example" : "example.org",
"type" : "string"
}
},
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The account has been deactivated.",
"schema" : {
"properties" : {
"id_server_unbind_result" : {
"description" : "An indicator as to whether or not the homeserver was able to unbind\nthe user's 3PIDs from the identity server(s). ``success`` indicates\nthat all identifiers have been unbound from the identity server while\n``no-support`` indicates that one or more identifiers failed to unbind\ndue to the identity server refusing the request or the homeserver\nbeing unable to determine an identity server to unbind from. This\nmust be ``success`` if the homeserver has no identifiers to unbind\nfor the user.",
"enum" : [ "success", "no-support" ],
"example" : "success",
"type" : "string"
}
},
"required" : [ "id_server_unbind_result" ],
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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`_ to\nensure the user changing the password is actually the owner of the\naccount.\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. The homeserver SHOULD NOT revoke the\naccess token provided in the request. Whether other access tokens for\nthe user are revoked depends on the request parameters.",
"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"
},
"logout_devices" : {
"description" : "Whether the user's other access tokens, and their associated devices, should be\nrevoked if the request succeeds. Defaults to true.\n\nWhen ``false``, the server can still take advantage of `the soft logout method <#soft-logout>`_\nfor the user's remaining devices.",
"example" : true,
"type" : "boolean"
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"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.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Gets information about the owner of an access token.",
"tags" : [ "User data" ]
}
},
"/_matrix/client/r0/capabilities" : {
"get" : {
"description" : "Gets information about the server's supported feature set\nand other relevant capabilities.",
"operationId" : "getCapabilities",
"parameters" : [ ],
"responses" : {
"200" : {
"description" : "The capabilities of the server.",
"examples" : {
"application/json" : {
"capabilities" : {
"com.example.custom.ratelimit" : {
"max_requests_per_hour" : 600
},
"m.change_password" : {
"enabled" : false
},
"m.room_versions" : {
"available" : {
"1" : "stable",
"2" : "stable",
"3" : "unstable",
"test-version" : "unstable"
},
"default" : "1"
}
}
}
},
"schema" : {
"properties" : {
"capabilities" : {
"additionalProperties" : {
"type" : "object"
},
"description" : "The custom capabilities the server supports, using the\nJava package naming convention.",
"properties" : {
"m.change_password" : {
"description" : "Capability to indicate if the user can change their password.",
"properties" : {
"enabled" : {
"description" : "True if the user can change their password, false otherwise.",
"example" : false,
"type" : "boolean"
}
},
"required" : [ "enabled" ],
"title" : "ChangePasswordCapability",
"type" : "object"
},
"m.room_versions" : {
"description" : "The room versions the server supports.",
"properties" : {
"available" : {
"additionalProperties" : {
"description" : "The stability of the room version.",
"enum" : [ "stable", "unstable" ],
"title" : "RoomVersionStability",
"type" : "string"
},
"description" : "A detailed description of the room versions the server supports.",
"title" : "AvailableRoomVersions",
"type" : "object"
},
"default" : {
"description" : "The default room version the server is using for new rooms.",
"example" : "1",
"type" : "string"
}
},
"required" : [ "default", "available" ],
"title" : "RoomVersionsCapability",
"type" : "object"
}
},
"title" : "Capabilities",
"type" : "object"
}
},
"required" : [ "capabilities" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Gets information about the server's capabilities.",
"tags" : [ "Capabilities" ]
}
},
"/_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\n1. The ``m.room.create`` event itself. Must be the first event in the\n room.\n\n2. An ``m.room.member`` event for the creator to join the room. This is\n needed so the remaining events can be sent.\n\n3. A default ``m.room.power_levels`` event, giving the room creator\n (and not other members) permission to send state events. Overridden\n by the ``power_level_content_override`` parameter.\n\n4. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,\n ``m.room.history_visibility``, and ``m.room.guest_access`` state events.\n\n5. Events listed in ``initial_state``, in the order that they are\n listed.\n\n6. Events implied by ``name`` and ``topic`` (``m.room.name`` and ``m.room.topic``\n state events).\n\n7. Invite events implied by ``invite`` and ``invite_3pid`` (``m.room.member`` with\n ``membership: invite`` and ``m.room.third_party_invite``).\n\nThe available presets do the following with respect to room state:\n\n======================== ============== ====================== ================ =========\n Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other\n======================== ============== ====================== ================ =========\n``private_chat`` ``invite`` ``shared`` ``can_join``\n``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.\n``public_chat`` ``public`` ``shared`` ``forbidden``\n======================== ============== ====================== ================ =========\n\nThe server will create a ``m.room.create`` event in the room with the\nrequesting user as the creator, alongside other keys provided in the\n``creation_content``.",
"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, such as ``m.federate``, to be added to the content\nof the `m.room.create`_ event. The server will clobber the following\nkeys: ``creator``, ``room_version``. Future versions of the specification\nmay allow the server to clobber other keys.",
"title" : "CreationContent",
"type" : "object"
},
"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 ``preset``, but gets\noverriden by ``name`` and ``topic`` keys.",
"items" : {
"properties" : {
"content" : {
"description" : "The content of the event.",
"type" : "object"
},
"state_key" : {
"description" : "The state_key of the state event. Defaults to an empty string.",
"type" : "string"
},
"type" : {
"description" : "The type of event to send.",
"type" : "string"
}
},
"required" : [ "type", "content" ],
"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_access_token" : {
"description" : "An access token previously registered with the identity server. Servers\ncan treat this as optional to distinguish between r0.5-compatible clients\nand this specification version.",
"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", "id_access_token", "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"
},
"power_level_content_override" : {
"description" : "The power level content to override in the default power level\nevent. This object is applied on top of the generated `m.room.power_levels`_\nevent content prior to it being sent to the room. Defaults to\noverriding nothing.",
"title" : "Power Level Event Content",
"type" : "object"
},
"preset" : {
"description" : "Convenience parameter for setting various default state events\nbased on a preset.\n\nIf unspecified, the server should use the ``visibility`` to determine\nwhich preset to use. A visbility of ``public`` equates to a preset of\n``public_chat`` and ``private`` visibility equates to a preset of\n``private_chat``.",
"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``.\n\nThe complete room alias will become the canonical alias for\nthe room.",
"type" : "string"
},
"room_version" : {
"description" : "The room version to set for the room. If not provided, the homeserver is\nto use its configured default. If provided, the homeserver will return a\n400 error with the errcode ``M_UNSUPPORTED_ROOM_VERSION`` if it does not\nsupport the room version.",
"example" : "1",
"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"
}
},
"required" : [ "room_id" ],
"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``).\n\n- The homeserver doesn't support the requested room version, or\n one or more users being invited to the new room are residents\n of a homeserver which does not support the requested room version.\n The ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these\n cases.",
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"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/list/appservice/{networkId}/{roomId}" : {
"put" : {
"description" : "Updates the visibility of a given room on the application service's room\ndirectory.\n\nThis API is similar to the room directory visibility API used by clients\nto update the homeserver's more general room directory.\n\nThis API requires the use of an application service access token (``as_token``)\ninstead of a typical client's access_token. This API cannot be invoked by\nusers who are not identified as application services.",
"operationId" : "updateAppserviceRoomDirectoryVsibility",
"parameters" : [ {
"description" : "The protocol (network) ID to update the room list for. This would\nhave been provided by the application service as being listed as\na supported protocol.",
"in" : "path",
"name" : "networkId",
"required" : true,
"type" : "string",
"x-example" : "irc"
}, {
"description" : "The room ID to add to the directory.",
"in" : "path",
"name" : "roomId",
"required" : true,
"type" : "string",
"x-example" : "!somewhere:example.org"
}, {
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"properties" : {
"visibility" : {
"description" : "Whether the room should be visible (public) in the directory\nor not (private).",
"enum" : [ "public", "private" ],
"example" : "public",
"type" : "string"
}
},
"required" : [ "visibility" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The room's directory visibility has been updated.",
"examples" : {
"application/json" : { }
},
"schema" : {
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Updates a room's visibility in the application service's room directory.",
"tags" : [ "Application service room directory 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\nroom aliases can only be deleted by their creator or a server administrator.\n\n.. Note::\n Servers may choose to update the ``alt_aliases`` for the ``m.room.canonical_alias``\n state event in the room when an alias is removed. Servers which choose to update the\n canonical alias event are recommended to, in addition to their other relevant permission\n checks, delete the alias and return a successful response even if the user does not\n have permission to update the ``m.room.canonical_alias`` event.",
"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"
}
},
"404" : {
"description" : "There is no mapped room ID for this room alias.",
"examples" : {
"application/json" : {
"errcode" : "M_NOT_FOUND",
"error" : "Room alias #monkeys:example.org not found."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"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" : "body",
"required" : true,
"schema" : {
"example" : {
"room_id" : "!abnjk1jdasj98:capuchins.com"
},
"properties" : {
"room_id" : {
"description" : "The room ID to set.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Create a new mapping from room alias to room ID.",
"tags" : [ "Room directory" ]
}
},
"/_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"
}, {
"description" : "The servers to attempt to join the room through. One of the servers\nmust be participating in the room.",
"in" : "query",
"items" : {
"type" : "string"
},
"name" : "server_name",
"type" : "array",
"x-example" : [ "matrix.org", "elsewhere.ca" ]
}, {
"in" : "body",
"name" : "third_party_signed",
"schema" : {
"properties" : {
"third_party_signed" : {
"description" : "A signature of an ``m.third_party_invite`` token to prove that this user\nowns a third party identity which has been invited to the room.",
"properties" : {
"mxid" : {
"description" : "The Matrix ID of the invitee.",
"example" : "@bob:example.org",
"type" : "string"
},
"sender" : {
"description" : "The Matrix ID of the user who issued the invite.",
"example" : "@alice:example.org",
"type" : "string"
},
"signatures" : {
"additionalProperties" : {
"additionalProperties" : {
"type" : "string"
},
"type" : "object"
},
"description" : "A signatures object containing a signature of the entire signed object.",
"example" : {
"example.org" : {
"ed25519:0" : "some9signature"
}
},
"title" : "Signatures",
"type" : "object"
},
"token" : {
"description" : "The state key of the m.third_party_invite event.",
"example" : "random8nonce",
"type" : "string"
}
},
"required" : [ "sender", "mxid", "token", "signatures" ],
"title" : "Third Party Signed",
"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" : {
"properties" : {
"room_id" : {
"description" : "The joined room ID.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "signed_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" : "object"
},
"type" : "object"
},
"description" : "One-time keys for the queried devices. A map from user ID, to a\nmap from devices to a map from ``<algorithm>:<key_id>`` to the key object.\n\nSee the `key algorithms <#key-algorithms>`_ section for information\non the Key Object format.",
"example" : {
"@alice:example.com" : {
"JLAFKJWSCS" : {
"signed_curve25519:AAAAHg" : {
"key" : "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
"signatures" : {
"@alice:example.com" : {
"ed25519:JLAFKJWSCS" : "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
}
}
}
}
}
},
"type" : "object"
}
},
"required" : [ "one_time_keys" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Claim one-time encryption keys.",
"tags" : [ "End-to-end encryption" ]
}
},
"/_matrix/client/r0/login" : {
"get" : {
"description" : "Gets the homeserver's supported login types to authenticate users. Clients\nshould pick one of these and supply it as the ``type`` when logging in.",
"operationId" : "getLoginFlows",
"responses" : {
"200" : {
"description" : "The login types the homeserver supports",
"examples" : {
"application/json" : {
"flows" : [ {
"type" : "m.login.password"
} ]
}
},
"schema" : {
"properties" : {
"flows" : {
"description" : "The homeserver's supported login types",
"items" : {
"properties" : {
"type" : {
"description" : "The login type. This is supplied as the ``type`` when\nlogging in.",
"type" : "string"
}
},
"title" : "LoginFlow",
"type" : "object"
},
"type" : "array"
}
},
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"summary" : "Get the supported login types to authenticate users",
"tags" : [ "Session management" ]
},
"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" : {
"identifier" : {
"type" : "m.id.user",
"user" : "cheeky_monkey"
},
"initial_device_display_name" : "Jungle Phone",
"password" : "ilovebananas",
"type" : "m.login.password"
},
"properties" : {
"address" : {
"description" : "Third party identifier for the user. Deprecated in favour of ``identifier``.",
"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"
},
"identifier" : {
"additionalProperties" : true,
"description" : "Identification information for the user.",
"properties" : {
"type" : {
"description" : "The type of identification. See `Identifier types`_ for supported values and additional property descriptions.",
"type" : "string"
}
},
"required" : [ "type" ],
"title" : "User identifier",
"type" : "object"
},
"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'. Deprecated in favour of ``identifier``.",
"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. Deprecated in favour of ``identifier``.",
"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",
"well_known" : {
"m.homeserver" : {
"base_url" : "https://example.org"
},
"m.identity_server" : {
"base_url" : "https://id.example.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"
},
"well_known" : {
"additionalProperties" : {
"description" : "Application-dependent keys using Java package naming convention.",
"type" : "object"
},
"description" : "Optional client configuration provided by the server. If present,\nclients SHOULD use the provided object to reconfigure themselves,\noptionally validating the URLs within. This object takes the same\nform as the one returned from .well-known autodiscovery.",
"example" : {
"m.homeserver" : {
"base_url" : "https://matrix.example.com"
},
"m.identity_server" : {
"base_url" : "https://identity.example.com"
},
"org.example.custom.property" : {
"app_url" : "https://custom.app.example.org"
}
},
"properties" : {
"m.homeserver" : {
"description" : "Used by clients to discover homeserver information.",
"properties" : {
"base_url" : {
"description" : "The base URL for the homeserver for client-server connections.",
"example" : "https://matrix.example.com",
"type" : "string"
}
},
"required" : [ "base_url" ],
"title" : "Homeserver Information",
"type" : "object"
},
"m.identity_server" : {
"description" : "Used by clients to discover identity server information.",
"properties" : {
"base_url" : {
"description" : "The base URL for the identity server for client-server connections.",
"example" : "https://identity.example.com",
"type" : "string"
}
},
"required" : [ "base_url" ],
"title" : "Identity Server Information",
"type" : "object"
}
},
"required" : [ "m.homeserver" ],
"title" : "Discovery Information",
"type" : "object"
}
},
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"403" : {
"description" : "The login attempt failed. This can include one of the following error codes:\n * ``M_FORBIDDEN``: The provided authentication data was incorrect.\n * ``M_USER_DEACTIVATED``: The user has been deactivated.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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. The device associated with the access token is also deleted.\n`Device keys <#device-keys>`_ for the device are deleted alongside the device.",
"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. All devices\nfor the user are also deleted. `Device keys <#device-keys>`_ for the device are\ndeleted alongside the device.\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" : "integer",
"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" : {
"content" : {
"body" : "This is an example text message",
"format" : "org.matrix.custom.html",
"formatted_body" : "<b>This is an example text message</b>",
"msgtype" : "m.text"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!jEsUZKDJdhlrceRyVU:example.org",
"sender" : "@example:example.org",
"type" : "m.room.message",
"unsigned" : {
"age" : 1234
}
},
"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"
},
"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/{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"
}
},
"required" : [ "presence" ],
"type" : "object"
}
},
"403" : {
"description" : "You are not allowed to see this user's presence status.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "You are not allowed to see their presence"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"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.",
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "integer"
}, {
"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.",
"schema" : {
"description" : "A list of the rooms on the server.",
"example" : {
"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
},
"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" : "integer"
},
"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" : "integer"
}
},
"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"
},
"include_all_networks" : false,
"limit" : 10,
"third_party_instance_id" : "irc"
},
"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"
},
"include_all_networks" : {
"description" : "Whether or not to include all known networks/protocols from\napplication services on the homeserver. Defaults to false.",
"example" : false,
"type" : "boolean"
},
"limit" : {
"description" : "Limit the number of results returned.",
"type" : "integer"
},
"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"
},
"third_party_instance_id" : {
"description" : "The specific third party network/protocol to request from the\nhomeserver. Can only be used if ``include_all_networks`` is false.",
"example" : "irc",
"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" : "integer"
},
"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" : "integer"
}
},
"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" : {
"format" : {
"description" : "The format to use when sending notifications to the Push\nGateway.",
"type" : "string"
},
"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"
}
},
"required" : [ "pushkey", "app_id", "kind", "app_display_name", "device_display_name", "lang", "data" ],
"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" : {
"format" : "event_id_only",
"url" : "https://push-gateway.location.here/_matrix/push/v1/notify"
},
"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.\n\nIf the ``kind`` is ``\"email\"``, this is ``\"m.email\"``.",
"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" : {
"format" : {
"description" : "The format to send notifications in to Push Gateways if the\n``kind`` is ``http``. The details about what fields the\nhomeserver should send to the push gateway are defined in the\n`Push Gateway Specification`_. Currently the only format\navailable is 'event_id_only'.",
"type" : "string"
},
"url" : {
"description" : "Required if ``kind`` is ``http``. The URL to use to send\nnotifications to. MUST be an HTTPS URL with a path of \n``/_matrix/push/v1/notify``.",
"example" : "https://push-gateway.location.here/_matrix/push/v1/notify",
"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. ``\"email\"`` makes a pusher that emails the\nuser with unread notifications. ``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.\n\nIf the ``kind`` is ``\"email\"``, this is the email address to\nsend notifications to.",
"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" : {
"description" : "An empty object.",
"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" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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"
}, {
"key" : "type",
"kind" : "event_match",
"pattern" : "m.room.message"
} ],
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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"
},
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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.\n\nWhen creating push rules, they MUST be enabled by default.",
"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.\n\nRequired for ``sender_notification_permission`` conditions. The field in\nthe power level event the user needs a minimum power level for. Fields\nmust be specified under the ``notifications`` property in the power level\nevent's ``content``.",
"type" : "string",
"x-example" : "content.body"
},
"kind" : {
"description" : "The kind of condition to apply. See `conditions <#conditions>`_ for\nmore information on the allowed kinds and how they work.",
"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 push rule was created/updated.",
"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" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Add or change a push rule.",
"tags" : [ "Push notifications" ]
}
},
"/_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions" : {
"get" : {
"description" : "This endpoint get the actions for the specified push rule.",
"operationId" : "getPushRuleActions",
"parameters" : [ {
"description" : "Either ``global`` or ``device/<profile_tag>`` to specify global\nrules or device rules for the given ``profile_tag``.",
"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 actions for this push rule.",
"examples" : {
"application/json" : {
"actions" : [ "notify" ]
}
},
"schema" : {
"properties" : {
"actions" : {
"description" : "The action(s) to perform for this rule.",
"items" : {
"type" : "string"
},
"type" : "array"
}
},
"required" : [ "actions" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "The actions for a push rule",
"tags" : [ "Push notifications" ]
},
"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" : {
"get" : {
"description" : "This endpoint gets whether the specified push rule is enabled.",
"operationId" : "isPushRuleEnabled",
"parameters" : [ {
"description" : "Either ``global`` or ``device/<profile_tag>`` to specify global\nrules or device rules for the given ``profile_tag``.",
"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" : "cake"
}, {
"description" : "The identifier for the rule.\n",
"in" : "path",
"name" : "ruleId",
"required" : true,
"type" : "string",
"x-example" : "nocake"
} ],
"responses" : {
"200" : {
"description" : "Whether the push rule is enabled.",
"examples" : {
"application/json" : {
"enabled" : true
}
},
"schema" : {
"properties" : {
"enabled" : {
"description" : "Whether the push rule is enabled or not.",
"type" : "boolean"
}
},
"required" : [ "enabled" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get whether a push rule is enabled",
"tags" : [ "Push notifications" ]
},
"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`_, except in\nthe cases where a guest account is being registered.\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`_.\n\nWhen registering a guest account, all parameters in the request body\nwith the exception of ``initial_device_display_name`` MUST BE ignored\nby the server. The server MUST pick a ``device_id`` for the account\nregardless of input.\n\nAny user ID returned by this API must conform to the grammar given in the\n`Matrix specification <../appendices.html#user-identifiers>`_.",
"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.",
"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"
},
"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"
},
"inhibit_login" : {
"description" : "If true, an ``access_token`` and ``device_id`` should not be\nreturned from this call, therefore preventing an automatic\nlogin. Defaults to false.",
"example" : false,
"type" : "boolean"
},
"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.\nRequired if the ``inhibit_login`` option is false.",
"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.\nRequired if the ``inhibit_login`` option is false.",
"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 <../appendices.html#user-identifiers>`_.",
"type" : "string"
}
},
"required" : [ "user_id" ],
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"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"
}
},
"403" : {
"description" : "The homeserver does not permit registering the account. This response\ncan be used to identify that a particular ``kind`` of account is not\nallowed, or that registration is generally not supported by the homeserver.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "Registration is disabled"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"summary" : "Checks to see if a username is available on the server.",
"tags" : [ "User data" ]
}
},
"/_matrix/client/r0/rooms/{roomId}/aliases" : {
"get" : {
"description" : "Get a list of aliases maintained by the local server for the\ngiven room.\n\nThis endpoint can be called by users who are in the room (external\nusers receive an ``M_FORBIDDEN`` error response). If the room's\n``m.room.history_visibility`` maps to ``world_readable``, any\nuser can call this endpoint.\n\nServers may choose to implement additional access control checks here,\nsuch as allowing server administrators to view aliases regardless of\nmembership.\n\n.. Note::\n Clients are recommended not to display this list of aliases prominently\n as they are not curated, unlike those listed in the ``m.room.canonical_alias``\n state event.",
"operationId" : "getLocalAliases",
"parameters" : [ {
"description" : "The room ID to find local aliases of.",
"in" : "path",
"name" : "roomId",
"required" : true,
"type" : "string",
"x-example" : "!abc123:example.org"
} ],
"responses" : {
"200" : {
"description" : "The list of local aliases for the room.",
"examples" : {
"application/json" : {
"aliases" : [ "#somewhere:example.com", "#another:example.com", "#hat_trick:example.com" ]
}
},
"schema" : {
"properties" : {
"aliases" : {
"description" : "The server's local aliases on the room. Can be empty.",
"items" : {
"type" : "string"
},
"type" : "array"
}
},
"required" : [ "aliases" ],
"type" : "object"
}
},
"403" : {
"description" : "The user is not permitted to retrieve the list of local aliases for the room.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "You are not a member of the room."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get a list of local aliases on a given room.",
"tags" : [ "Room directory" ]
}
},
"/_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. This will be supplied as the ``reason`` on the target's updated `m.room.member`_ event.",
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Ban a user in the room.",
"tags" : [ "Room membership" ]
}
},
"/_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 must leave the room\nbefore calling this API.",
"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"
}
},
"400" : {
"description" : "The user has not left the room",
"examples" : {
"application/json" : {
"errcode" : "M_UNKNOWN",
"error" : "User @example:matrix.org is in room !au1ba7o:matrix.org"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Stop the requesting user remembering about a particular room.",
"tags" : [ "Room membership" ]
}
},
"/_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_access_token" : "abc123_OpaqueString",
"id_server" : "matrix.org",
"medium" : "email"
},
"properties" : {
"address" : {
"description" : "The invitee's third party identifier.",
"type" : "string"
},
"id_access_token" : {
"description" : "An access token previously registered with the identity server. Servers\ncan treat this as optional to distinguish between r0.5-compatible clients\nand this specification version.",
"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", "id_access_token", "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"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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"
}
},
"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- One or more users being invited to the room are residents of a\n homeserver which does not support the requested room version. The\n ``errcode`` will be ``M_UNSUPPORTED_ROOM_VERSION`` in these cases.",
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"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"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : {
"properties" : {
"third_party_signed" : {
"description" : "A signature of an ``m.third_party_invite`` token to prove that this user\nowns a third party identity which has been invited to the room.",
"properties" : {
"mxid" : {
"description" : "The Matrix ID of the invitee.",
"example" : "@bob:example.org",
"type" : "string"
},
"sender" : {
"description" : "The Matrix ID of the user who issued the invite.",
"example" : "@alice:example.org",
"type" : "string"
},
"signatures" : {
"additionalProperties" : {
"additionalProperties" : {
"type" : "string"
},
"type" : "object"
},
"description" : "A signatures object containing a signature of the entire signed object.",
"example" : {
"example.org" : {
"ed25519:0" : "some9signature"
}
},
"title" : "Signatures",
"type" : "object"
},
"token" : {
"description" : "The state key of the m.third_party_invite event.",
"example" : "random8nonce",
"type" : "string"
}
},
"required" : [ "sender", "mxid", "token", "signatures" ],
"title" : "Third Party Signed",
"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" : {
"properties" : {
"room_id" : {
"description" : "The joined room ID.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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.\n\nKicking a user adjusts the target member's membership state to be ``leave`` with an\noptional ``reason``. Like with other membership changes, a user can directly adjust\nthe target member's state by making a request to ``/rooms/<room id>/state/m.room.member/<user id>``.",
"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. This will be supplied as the \n``reason`` on the target's updated `m.room.member`_ event.",
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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"
}, {
"description" : "The point in time (pagination token) to return members for in the room.\nThis token can be obtained from a ``prev_batch`` token returned for\neach room by the sync API. Defaults to the current state of the room,\nas determined by the server.",
"in" : "query",
"name" : "at",
"type" : "string",
"x-example" : "YWxsCgpOb25lLDM1ODcwOA"
}, {
"description" : "The kind of membership to filter for. Defaults to no filtering if\nunspecified. When specified alongside ``not_membership``, the two\nparameters create an 'or' condition: either the membership *is*\nthe same as ``membership`` **or** *is not* the same as ``not_membership``.",
"enum" : [ "join", "invite", "leave", "ban" ],
"in" : "query",
"name" : "membership",
"type" : "string",
"x-example" : "join"
}, {
"description" : "The kind of membership to exclude from the results. Defaults to no\nfiltering if unspecified.",
"enum" : [ "join", "invite", "leave", "ban" ],
"in" : "query",
"name" : "not_membership",
"type" : "string",
"x-example" : "leave"
} ],
"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" : [ {
"content" : {
"avatar_url" : "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname" : "Alice Margatroid",
"membership" : "join"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "@alice:example.org",
"type" : "m.room.member",
"unsigned" : {
"age" : 1234
}
} ]
}
},
"schema" : {
"properties" : {
"chunk" : {
"items" : {
"allOf" : [ {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Room Event",
"type" : "object"
}, {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "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.\nState keys starting with an ``@`` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.",
"type" : "string"
}
},
"required" : [ "state_key" ],
"title" : "State Event",
"type" : "object"
} ],
"description" : "State Events have the following fields.",
"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 inside the event's ``unsigned`` data.\nIf present, this contains an array of ``StrippedState`` Events. These events provide information\non a subset of state events such as the room name.\n\nThe user for which a membership applies is represented by the ``state_key``. Under some conditions,\nthe ``sender`` and ``state_key`` may not match - this may be interpreted as the ``sender`` affecting\nthe membership state of the ``state_key`` user.\n\nThe ``membership`` for a given user can change over time. The table below represents the various changes\nover time and how clients and servers must interpret those changes. Previous membership can be retrieved\nfrom the ``prev_content`` object on an event. If not present, the user's previous membership must be assumed\nas ``leave``.\n\n.. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions.\n\n.. csv-table::\n :header-rows: 1\n :stub-columns: 1\n\n \"\",\"to ``invite``\",\"to ``join``\",\"to ``leave``\",\"to ``ban``\",\"to ``knock``\"\n \"from ``invite``\",\"No change.\",\"User joined the room.\",\"If the ``state_key`` is the same as the ``sender``, the user rejected the invite. Otherwise, the ``state_key`` user had their invite revoked.\",\"User was banned.\",\"Not implemented.\"\n \"from ``join``\",\"Must never happen.\",\"``displayname`` or ``avatar_url`` changed.\",\"If the ``state_key`` is the same as the ``sender``, the user left. Otherwise, the ``state_key`` user was kicked.\",\"User was kicked and banned.\",\"Not implemented.\"\n \"from ``leave``\",\"New invitation sent.\",\"User joined.\",\"No change.\",\"User was banned.\",\"Not implemented.\"\n \"from ``ban``\",\"Must never happen.\",\"Must never happen.\",\"User was unbanned.\",\"No change.\",\"Not implemented.\"\n \"from ``knock``\",\"Not implemented.\",\"Not implemented.\",\"Not implemented.\",\"Not implemented.\",\"Not implemented.\"",
"properties" : {
"content" : {
"properties" : {
"avatar_url" : {
"description" : "The avatar URL for this user, if any.",
"type" : "string"
},
"displayname" : {
"description" : "The display name for this user, if any.",
"type" : "string"
},
"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" : {
"additionalProperties" : {
"additionalProperties" : {
"type" : "string"
},
"type" : "object"
},
"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"
},
"unsigned" : {
"description" : "Contains optional extra information about the event.",
"properties" : {
"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``,\n``sender``, and ``content`` keys.",
"properties" : {
"content" : {
"description" : "The ``content`` for the event.",
"title" : "EventContent",
"type" : "object"
},
"sender" : {
"description" : "The ``sender`` for the event.",
"type" : "string"
},
"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", "sender" ],
"title" : "StrippedState",
"type" : "object"
},
"type" : "array"
}
},
"title" : "UnsignedData",
"type" : "object"
}
},
"required" : [ "membership" ],
"title" : "EventContent",
"type" : "object"
},
"state_key" : {
"description" : "The ``user_id`` this membership event relates to. In all cases except for when ``membership`` is\n``join``, the user ID sending the event does not need to match the user ID in the ``state_key``,\nunlike other events. Regular authorisation rules still apply.",
"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.\n\n*Note*: This endpoint supports lazy-loading of room member events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.",
"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" : [ {
"content" : {
"body" : "This is an example text message",
"format" : "org.matrix.custom.html",
"formatted_body" : "<b>This is an example text message</b>",
"msgtype" : "m.text"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"type" : "m.room.message",
"unsigned" : {
"age" : 1234
}
}, {
"content" : {
"name" : "The room name"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "",
"type" : "m.room.name",
"unsigned" : {
"age" : 1234
}
}, {
"content" : {
"body" : "Gangnam Style",
"info" : {
"duration" : 2140786,
"h" : 320,
"mimetype" : "video/mp4",
"size" : 1563685,
"thumbnail_info" : {
"h" : 300,
"mimetype" : "image/jpeg",
"size" : 46144,
"w" : 300
},
"thumbnail_url" : "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
"w" : 480
},
"msgtype" : "m.video",
"url" : "mxc://example.org/a526eYUSFFxlgbQYZmo442"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"type" : "m.room.message",
"unsigned" : {
"age" : 1234
}
} ],
"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. The order depends on the ``dir`` parameter.\nFor ``dir=b`` events will be in reverse-chronological order,\nfor ``dir=f`` in chronological order, so that events start\nat the ``from`` point.",
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"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"
},
"state" : {
"description" : "A list of state events relevant to showing the ``chunk``. For example, if\n``lazy_load_members`` is enabled in the filter then this may contain\nthe membership events for the senders of events in the ``chunk``.\n\nUnless ``include_redundant_members`` is ``true``, the server\nmay remove membership events which would have already been\nsent to the client in prior calls to this endpoint, assuming\nthe membership of those members has not changed.",
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Room Event",
"type" : "object"
}, {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "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.\nState keys starting with an ``@`` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.",
"type" : "string"
}
},
"required" : [ "state_key" ],
"title" : "State Event",
"type" : "object"
} ],
"description" : "State Events have the following fields.",
"title" : "RoomStateEvent",
"type" : "object"
},
"type" : "array"
}
},
"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}/read_markers" : {
"post" : {
"description" : "Sets the position of the read marker for a given room, and optionally\nthe read receipt's location.",
"operationId" : "setReadMarker",
"parameters" : [ {
"description" : "The room ID to set the read marker in for the user.",
"in" : "path",
"name" : "roomId",
"required" : true,
"type" : "string",
"x-example" : "!somewhere:example.org"
}, {
"description" : "The read marker and optional read receipt locations.",
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"properties" : {
"m.fully_read" : {
"description" : "The event ID the read marker should be located at. The\nevent MUST belong to the room.",
"example" : "$somewhere:example.org",
"type" : "string"
},
"m.read" : {
"description" : "The event ID to set the read receipt location at. This is\nequivalent to calling ``/receipt/m.read/$elsewhere:example.org``\nand is provided here to save that extra call.",
"example" : "$elsewhere:example.org",
"type" : "string"
}
},
"required" : [ "m.fully_read" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The read marker, and read receipt if provided, have been updated.",
"schema" : {
"properties" : { },
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Set the position of the read marker for a room.",
"tags" : [ "Read Markers" ]
}
},
"/_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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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:example.org"
}, {
"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"
}
},
"required" : [ "event_id" ],
"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" : [ {
"content" : {
"join_rule" : "public"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "",
"type" : "m.room.join_rules",
"unsigned" : {
"age" : 1234
}
}, {
"content" : {
"avatar_url" : "mxc://example.org/SEsfnsuifSDFSSEF",
"displayname" : "Alice Margatroid",
"membership" : "join"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "@alice:example.org",
"type" : "m.room.member",
"unsigned" : {
"age" : 1234
}
}, {
"content" : {
"creator" : "@example:example.org",
"m.federate" : true,
"predecessor" : {
"event_id" : "$something:example.org",
"room_id" : "!oldroom:example.org"
},
"room_version" : "1"
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "",
"type" : "m.room.create",
"unsigned" : {
"age" : 1234
}
}, {
"content" : {
"ban" : 50,
"events" : {
"m.room.name" : 100,
"m.room.power_levels" : 100
},
"events_default" : 0,
"invite" : 50,
"kick" : 50,
"notifications" : {
"room" : 20
},
"redact" : 50,
"state_default" : 50,
"users" : {
"@example:localhost" : 100
},
"users_default" : 0
},
"event_id" : "$143273582443PhrSn:example.org",
"origin_server_ts" : 1432735824653,
"room_id" : "!636q39766251:example.com",
"sender" : "@example:example.org",
"state_key" : "",
"type" : "m.room.power_levels",
"unsigned" : {
"age" : 1234
}
} ]
},
"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" : [ {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Room Event",
"type" : "object"
}, {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "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.\nState keys starting with an ``@`` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.",
"type" : "string"
}
},
"required" : [ "state_key" ],
"title" : "State Event",
"type" : "object"
} ],
"description" : "State Events have the following fields.",
"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}/{stateKey}" : {
"get" : {
"description" : ".. For backwards compatibility with older links...\n.. _`get-matrix-client-unstable-rooms-roomid-state-eventtype`:\n\nLooks 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. Defaults to an empty string. When\nan empty string, the trailing slash on this endpoint is optional.",
"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" : ".. For backwards compatibility with older links...\n.. _`put-matrix-client-unstable-rooms-roomid-state-eventtype`:\n\nState 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\nIf the event type being sent is ``m.room.canonical_alias`` servers\nSHOULD ensure that any new aliases being listed in the event are valid\nper their grammar/syntax and that they point to the room ID where the\nstate event is to be sent. Servers do not validate aliases which are\nbeing removed or are already present in the state event.\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. When\nan empty string, the trailing slash on this endpoint is optional.",
"in" : "path",
"name" : "stateKey",
"required" : true,
"type" : "string",
"x-example" : "@alice:example.com"
}, {
"in" : "body",
"name" : "body",
"schema" : {
"example" : {
"avatar_url" : "mxc://localhost/SEsfnsuifSDFSSEF",
"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"
}
},
"required" : [ "event_id" ],
"type" : "object"
}
},
"400" : {
"description" : "The sender's request is malformed.\n\nSome example error codes include:\n\n* ``M_INVALID_PARAMETER``: One or more aliases within the ``m.room.canonical_alias``\n event have invalid syntax.\n\n* ``M_BAD_ALIAS``: One or more aliases within the ``m.room.canonical_alias`` event\n do not point to the room ID for which the state event is to be sent to.",
"examples" : {
"application/json" : {
"errcode" : "M_BAD_ALIAS",
"error" : "The alias '#hello:example.org' does not point to this room."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"403" : {
"description" : "The sender doesn't have permission to send the event into the room.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "You do not have permission to send the event."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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."
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Unban a user from the room.",
"tags" : [ "Room membership" ]
}
},
"/_matrix/client/r0/rooms/{roomId}/upgrade" : {
"post" : {
"description" : "Upgrades the given room to a particular room version.",
"operationId" : "upgradeRoom",
"parameters" : [ {
"description" : "The ID of the room to upgrade.",
"in" : "path",
"name" : "roomId",
"required" : true,
"type" : "string",
"x-example" : "!oldroom:example.org"
}, {
"description" : "The request body",
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"example" : {
"new_version" : "2"
},
"properties" : {
"new_version" : {
"description" : "The new version for the room.",
"type" : "string"
}
},
"required" : [ "new_version" ],
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "The room was successfully upgraded.",
"examples" : {
"application/json" : {
"replacement_room" : "!newroom:example.org"
}
},
"schema" : {
"properties" : {
"replacement_room" : {
"description" : "The ID of the new room.",
"type" : "string"
}
},
"required" : [ "replacement_room" ],
"type" : "object"
}
},
"400" : {
"description" : "The request was invalid. One way this can happen is if the room version\nrequested is not supported by the homeserver.",
"examples" : {
"application/json" : {
"errcode" : "M_UNSUPPORTED_ROOM_VERSION",
"error" : "This server does not support that room version"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"403" : {
"description" : "The user is not permitted to upgrade the room.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "You cannot upgrade this room"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Upgrades a room to a new room version.",
"tags" : [ "Room upgrades" ]
}
},
"/_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" : "Include Event Context",
"type" : "object"
},
"filter" : {
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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" : "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 Criteria",
"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" : {
"content" : {
"body" : "This is an example text message",
"format" : "org.matrix.custom.html",
"formatted_body" : "<b>This is an example text message</b>",
"msgtype" : "m.text"
},
"event_id" : "$144429830826TWwbB:localhost",
"origin_server_ts" : 1432735824653,
"room_id" : "!qPewotXpIctQySfjSy:localhost",
"sender" : "@example:example.org",
"type" : "m.room.message",
"unsigned" : {
"age" : 1234
}
}
} ]
}
}
}
},
"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" : "integer"
},
"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.\n\nThe outer ``string`` key is the group key requested (eg: ``room_id``\nor ``sender``). The inner ``string`` key is the grouped value (eg:\na room's ID or a user's ID).",
"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" : [ {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Event",
"type" : "object"
},
"title" : "Events After",
"type" : "array"
},
"events_before" : {
"description" : "Events just before the result.",
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"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.\n\nThe ``string`` key is the user ID for which\nthe profile belongs to.",
"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" : [ {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "The event that matched.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Event",
"type" : "object"
}
},
"title" : "Result",
"type" : "object"
},
"title" : "Results",
"type" : "array"
},
"state" : {
"additionalProperties" : {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "sender", "origin_server_ts" ],
"title" : "Room Event",
"type" : "object"
} ],
"description" : "Room Events have the following fields.",
"properties" : {
"room_id" : {
"description" : "The ID of the room associated with this event. Will not be present on events\nthat arrive through ``/sync``, despite being required everywhere else.",
"type" : "string"
}
},
"required" : [ "room_id" ],
"title" : "Room Event",
"type" : "object"
}, {
"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", "content" ],
"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.",
"format" : "int64",
"type" : "integer"
},
"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", "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.\nState keys starting with an ``@`` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.",
"type" : "string"
}
},
"required" : [ "state_key" ],
"title" : "State Event",
"type" : "object"
} ],
"description" : "State Events have the following fields.",
"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``.\n\nThe ``string`` key is the room ID for which the ``State\nEvent`` array belongs to.",
"title" : "Current state",
"type" : "object"
}
},
"title" : "Result Room Events",
"type" : "object"
}
},
"title" : "Result 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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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/user/{userId}/account_data/{type}" : {
"get" : {
"description" : "Get some account_data for the client. This config is only visible to the user\nthat set the account_data.",
"operationId" : "getAccountData",
"parameters" : [ {
"description" : "The ID of the user to get 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 get. Custom types should be\nnamespaced to avoid clashes.",
"in" : "path",
"name" : "type",
"required" : true,
"type" : "string",
"x-example" : "org.example.custom.config"
} ],
"responses" : {
"200" : {
"description" : "The account data content for the given type.",
"schema" : {
"example" : {
"custom_account_data_key" : "custom_config_value"
},
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get some account_data for the user.",
"tags" : [ "User data" ]
},
"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" : "EventFilter",
"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 '.' characters 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 received 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" : "EventFilter",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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.",
"title" : "StateFilter",
"type" : "object"
},
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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"
}
},
"title" : "Filter",
"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.",
"schema" : {
"properties" : {
"filter_id" : {
"description" : "The ID of the filter that was created. Cannot start\nwith a ``{`` as this character is used to determine\nif the filter provided is inline JSON or a previously\ndeclared filter by homeservers on some APIs.",
"example" : "66696p746572",
"type" : "string"
}
},
"required" : [ "filter_id" ],
"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" : "EventFilter",
"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 '.' characters 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 received 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" : "EventFilter",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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.",
"title" : "StateFilter",
"type" : "object"
},
"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" : "EventFilter",
"type" : "object"
}, {
"properties" : {
"contains_url" : {
"description" : "If ``true``, includes only events with a ``url`` key in their content. If ``false``, excludes those events. If omitted, ``url`` key is not considered for filtering.",
"type" : "boolean"
},
"include_redundant_members" : {
"description" : "If ``true``, sends all membership events for all events, even if they have already\nbeen sent to the client. Does not\napply unless ``lazy_load_members`` is ``true``. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``false``.",
"type" : "boolean"
},
"lazy_load_members" : {
"description" : "If ``true``, enables lazy-loading of membership events. See\n`Lazy-loading room members <#lazy-loading-room-members>`_\nfor more information. Defaults to ``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.",
"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"
}
},
"title" : "Filter",
"type" : "object"
} ],
"type" : "object"
}
},
"404" : {
"description" : "Unknown filter."
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Download a filter",
"tags" : [ "Room participation" ]
}
},
"/_matrix/client/r0/user/{userId}/openid/request_token" : {
"post" : {
"description" : "Gets an OpenID token object that the requester may supply to another\nservice to verify their identity in Matrix. The generated token is only\nvalid for exchanging for user information from the federation API for\nOpenID.\n\nThe access token generated is only valid for the OpenID API. It cannot\nbe used to request another OpenID access token or call ``/sync``, for\nexample.",
"operationId" : "requestOpenIdToken",
"parameters" : [ {
"description" : "The user to request and OpenID token for. Should be the user who\nis authenticated for the request.",
"in" : "path",
"name" : "userId",
"required" : true,
"type" : "string",
"x-example" : "@alice:example.com"
}, {
"description" : "An empty object. Reserved for future expansion.",
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"example" : { },
"type" : "object"
}
} ],
"responses" : {
"200" : {
"description" : "OpenID token information. This response is nearly compatible with the\nresponse documented in the `OpenID 1.0 Specification <http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse>`_\nwith the only difference being the lack of an ``id_token``. Instead,\nthe Matrix homeserver's name is provided.",
"examples" : {
"application/json" : {
"access_token" : "SomeT0kenHere",
"expires_in" : 3600,
"matrix_server_name" : "example.com",
"token_type" : "Bearer"
}
},
"schema" : {
"properties" : {
"access_token" : {
"description" : "An access token the consumer may use to verify the identity of\nthe person who generated the token. This is given to the federation\nAPI ``GET /openid/userinfo`` to verify the user's identity.",
"type" : "string"
},
"expires_in" : {
"description" : "The number of seconds before this token expires and a new one must\nbe generated.",
"type" : "integer"
},
"matrix_server_name" : {
"description" : "The homeserver domain the consumer should use when attempting to\nverify the user's identity.",
"type" : "string"
},
"token_type" : {
"description" : "The string ``Bearer``.",
"type" : "string"
}
},
"required" : [ "access_token", "token_type", "matrix_server_name", "expires_in" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get an OpenID token object to verify the requester's identity.",
"tags" : [ "OpenID" ]
}
},
"/_matrix/client/r0/user/{userId}/rooms/{roomId}/account_data/{type}" : {
"get" : {
"description" : "Get some account_data for the client on a given room. This config is only\nvisible to the user that set the account_data.",
"operationId" : "getAccountDataPerRoom",
"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 get account_data for.",
"in" : "path",
"name" : "roomId",
"required" : true,
"type" : "string",
"x-example" : "!726s6s6q:example.com"
}, {
"description" : "The event type of the account_data to get. Custom types should be\nnamespaced to avoid clashes.",
"in" : "path",
"name" : "type",
"required" : true,
"type" : "string",
"x-example" : "org.example.custom.room.config"
} ],
"responses" : {
"200" : {
"description" : "The account data content for the given type.",
"schema" : {
"example" : {
"custom_account_data_key" : "custom_config_value"
},
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get some account_data for the user.",
"tags" : [ "User data" ]
},
"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" : {
"m.favourite" : {
"order" : 0.1
},
"u.Customers" : { },
"u.Work" : {
"order" : 0.7
}
}
}
},
"schema" : {
"properties" : {
"tags" : {
"additionalProperties" : {
"additionalProperties" : true,
"properties" : {
"order" : {
"description" : "A number in a range ``[0,1]`` describing a relative\nposition of the room under the given tag.",
"format" : "float",
"type" : "number"
}
},
"title" : "Tag",
"type" : "object"
},
"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" : "u.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" : "u.work"
}, {
"description" : "Extra data for the tag, e.g. ordering.",
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"additionalProperties" : true,
"example" : {
"order" : 0.25
},
"properties" : {
"order" : {
"description" : "A number in a range ``[0,1]`` describing a relative\nposition of the room under the given tag.",
"format" : "float",
"type" : "number"
}
},
"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" : "Performs a search for users. The homeserver may\ndetermine which subset of users are searched, however the homeserver\nMUST at a minimum consider the users the requesting user shares a\nroom with and those who reside in public rooms (known to the homeserver).\nThe search MUST consider local users to the homeserver, and SHOULD\nquery remote users as part of the search.\n\nThe search is performed case-insensitively on user IDs and display\nnames preferably using a collation determined based upon the \n``Accept-Language`` header provided in the request, if present.",
"operationId" : "searchUserDirectory",
"parameters" : [ {
"in" : "body",
"name" : "body",
"schema" : {
"properties" : {
"limit" : {
"description" : "The maximum number of results to return. Defaults to 10.",
"example" : 10,
"type" : "integer"
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Obtain TURN server credentials.",
"tags" : [ "VOIP" ]
}
},
"/_matrix/media/r0/config" : {
"get" : {
"description" : "This endpoint allows clients to retrieve the configuration of the content\nrepository, such as upload limitations.\nClients SHOULD use this as a guide when using content repository endpoints.\nAll values are intentionally left optional. Clients SHOULD follow\nthe advice given in the field description when the field is not available.\n\n**NOTE:** Both clients and server administrators should be aware that proxies\nbetween the client and the server may affect the apparent behaviour of content\nrepository APIs, for example, proxies may enforce a lower upload size limit\nthan is advertised by the server on this endpoint.",
"operationId" : "getConfig",
"produces" : [ "application/json" ],
"responses" : {
"200" : {
"description" : "The public content repository configuration for the matrix server.",
"examples" : {
"application/json" : {
"m.upload.size" : 50000000
}
},
"schema" : {
"properties" : {
"m.upload.size" : {
"description" : "The maximum size an upload can be in bytes.\nClients SHOULD use this as a guide when uploading content.\nIf not listed or null, the size limit should be treated as unknown.",
"format" : "int64",
"type" : "integer"
}
},
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"security" : [ {
"accessToken" : [ ]
} ],
"summary" : "Get the configuration for the content repository.",
"tags" : [ "Media" ]
}
},
"/_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"
}, {
"default" : true,
"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" : {
"description" : "**Required.** The bytes for the uploaded file.",
"type" : "file"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"502" : {
"description" : "The content is too large for the server to serve.",
"examples" : {
"application/json" : {
"errcode" : "M_TOO_LARGE",
"error" : "Content is too large to serve"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"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" : "A filename to give in the ``Content-Disposition`` header.",
"in" : "path",
"name" : "fileName",
"required" : true,
"type" : "string",
"x-example" : "filename.jpg"
}, {
"default" : true,
"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 ``fileName`` requested or the name of the file that was previously\nuploaded, if set.",
"type" : "string"
},
"Content-Type" : {
"description" : "The content type of the file that was previously uploaded.",
"type" : "string"
}
},
"schema" : {
"description" : "**Required.** The bytes for the uploaded file.",
"type" : "file"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"502" : {
"description" : "The content is too large for the server to serve.",
"examples" : {
"application/json" : {
"errcode" : "M_TOO_LARGE",
"error" : "Content is too large to serve"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"summary" : "Download content from the content repository. This is the same as\nthe download endpoint above, except permitting a desired file name.",
"tags" : [ "Media" ]
}
},
"/_matrix/media/r0/preview_url" : {
"get" : {
"description" : "Get information about a URL for the client. Typically this is called when a\nclient sees a URL in a message and wants to render a preview for the user.\n\n.. Note::\n Clients should consider avoiding this endpoint for URLs posted in encrypted\n rooms. Encrypted rooms often contain more sensitive information the users\n do not want to share with the homeserver, and this can mean that the URLs\n being shared should also not be shared with the homeserver.",
"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.",
"format" : "int64",
"in" : "query",
"name" : "ts",
"type" : "integer",
"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.",
"format" : "int64",
"type" : "integer"
},
"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" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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" : "example.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 be\nlarger than the size specified.",
"in" : "query",
"name" : "width",
"required" : true,
"type" : "integer",
"x-example" : 64
}, {
"description" : "The *desired* height of the thumbnail. The actual thumbnail may be\nlarger than the size specified.",
"in" : "query",
"name" : "height",
"required" : true,
"type" : "integer",
"x-example" : 64
}, {
"description" : "The desired resizing method. See the `thumbnailing <#thumbnails>`_\nsection for more information.",
"enum" : [ "crop", "scale" ],
"in" : "query",
"name" : "method",
"type" : "string",
"x-example" : "scale"
}, {
"default" : true,
"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" : {
"description" : "**Required.** The bytes for the thumbnail.",
"type" : "file"
}
},
"400" : {
"description" : "The request does not make sense to the server, or the server cannot thumbnail\nthe content. For example, the client requested non-integer dimensions or asked\nfor negatively-sized images.",
"examples" : {
"application/json" : {
"errcode" : "M_UNKNOWN",
"error" : "Cannot generate thumbnails for the requested content"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"413" : {
"description" : "The local content is too large for the server to thumbnail.",
"examples" : {
"application/json" : {
"errcode" : "M_TOO_LARGE",
"error" : "Content is too large to thumbnail"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"502" : {
"description" : "The remote content is too large for the server to thumbnail.",
"examples" : {
"application/json" : {
"errcode" : "M_TOO_LARGE",
"error" : "Content is too large to thumbnail"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
}
},
"summary" : "Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_\nsection for more information.",
"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: application/pdf"
}, {
"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"
},
"x-example" : "<bytes>"
} ],
"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"
}
},
"403" : {
"description" : "The user does not have permission to upload the content. Some reasons for this error include:\n\n- The server does not permit the file type.\n- The user has reached a quota for uploaded content.",
"examples" : {
"application/json" : {
"errcode" : "M_FORBIDDEN",
"error" : "Cannot upload this content"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"413" : {
"description" : "The uploaded content is too large for the server.",
"examples" : {
"application/json" : {
"errcode" : "M_TOO_LARGE",
"error" : "Cannot upload files larger than 100mb"
}
},
"schema" : {
"description" : "A Matrix-level Error",
"properties" : {
"errcode" : {
"description" : "An error code.",
"example" : "M_UNKNOWN",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "An unknown error occurred",
"type" : "string"
}
},
"required" : [ "errcode" ],
"type" : "object"
}
},
"429" : {
"description" : "This request was rate-limited.",
"schema" : {
"description" : "The rate limit was reached for this request",
"properties" : {
"errcode" : {
"description" : "The M_LIMIT_EXCEEDED error code",
"example" : "M_LIMIT_EXCEEDED",
"type" : "string"
},
"error" : {
"description" : "A human-readable error message.",
"example" : "Too many requests",
"type" : "string"
},
"retry_after_ms" : {
"description" : "The amount of time in milliseconds the client should wait\nbefore trying the request again.",
"example" : 2000,
"type" : "integer"
}
},
"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"
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment