{ "components": { "securitySchemes": { "accessTokenBearer": { "description": "The `access_token` obtained during [account registration](https://spec.matrix.org/v1.19/client-server-api/#account-registration)\nor [login](https://spec.matrix.org/v1.19/client-server-api/#login), using the `Authorization: Bearer` header.\n\nIt can also be the `as_token` of an application service.\n\nThis is the preferred method.", "scheme": "bearer", "type": "http" }, "accessTokenQuery": { "description": "**Deprecated.** The `access_token` obtained during [account registration](https://spec.matrix.org/v1.19/client-server-api/#account-registration)\nor [login](https://spec.matrix.org/v1.19/client-server-api/#login), as a query parameter.\n\nIt can also be the `as_token` of an application service.", "in": "query", "name": "access_token", "type": "apiKey" }, "appserviceAccessTokenBearer": { "description": "The `as_token` of an application service, using the `Authorization: Bearer`\nheader.\n\nThis is the preferred method.", "scheme": "bearer", "type": "http" }, "appserviceAccessTokenQuery": { "description": "**Deprecated.** The `as_token` of an application service, as a query\nparameter.", "in": "query", "name": "access_token", "type": "apiKey" } } }, "info": { "title": "Matrix Client-Server API", "version": "v1.19" }, "openapi": "3.1.0", "paths": { "/.well-known/matrix/client": { "get": { "description": "Gets discovery information about the domain. The file may include\nadditional keys, which MUST follow the Java package naming convention,\ne.g. `com.example.myapp.property`. This ensures property names are\nsuitably namespaced for each application and reduces the risk of\nclashes.\n\n**NOTE:** \nThis endpoint should be accessed with the hostname of the homeserver's\n[server name](https://spec.matrix.org/v1.19/appendices/#server-name) by making a\nGET request to `https://hostname/.well-known/matrix/client`.\n\n\nNote that this endpoint is not necessarily handled by the homeserver,\nbut by another webserver, to be used for discovering the homeserver URL.", "operationId": "getWellknown", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "description": "Application-dependent keys using Java package naming convention." }, "description": "Used by clients to determine the homeserver, identity server, and other\noptional components they should be interacting with.", "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", "format": "uri", "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", "format": "uri", "type": "string" } }, "required": [ "base_url" ], "title": "Identity Server Information", "type": "object" } }, "required": [ "m.homeserver" ], "title": "Discovery Information", "type": "object" } } }, "description": "Server discovery information." }, "404": { "description": "No server discovery information available." } }, "summary": "Gets Matrix server discovery information about the domain.", "tags": [ "Server administration" ] } }, "/.well-known/matrix/policy_server": { "get": { "description": "Gets public key information for a [Policy Server](https://spec.matrix.org/v1.19/client-server-api/#policy-servers).\n\n**NOTE:** \nLike the [well-known discovery URI](https://spec.matrix.org/v1.19/client-server-api/#well-known-uris),\nthis endpoint should be accessed with the hostname of the Policy Server's\n[server name](https://spec.matrix.org/v1.19/appendices/#server-name) by making a\nGET request to `https://hostname/.well-known/matrix/policy_server`.\n\n\nNote that this endpoint is not necessarily handled by the homeserver or\nPolicy Server. It may be served by another webserver.", "operationId": "getWellknownPolicy", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "public_keys": { "ed25519": "6yhHGKhCiXTSEN2ksjV7kX_N6rBQZ3Xb-M7LlC6NS-s" } } } }, "schema": { "properties": { "public_keys": { "additionalProperties": { "description": "The unpadded base64-encoded public key for the key algorithm.", "type": "string" }, "description": "The unpadded base64-encoded public keys for the Policy Server. MUST contain\nat least `ed25519`.", "properties": { "ed25519": { "description": "The unpadded base64-encoded ed25519 public key for the Policy Server.", "type": "string" } }, "required": [ "ed25519" ], "type": "object" } }, "required": [ "public_keys" ], "type": "object" } } }, "description": "Public keys for the Policy Server. Can be supplied to the [`m.room.policy`](https://spec.matrix.org/v1.19/client-server-api/#mroompolicy)\nstate event." }, "404": { "description": "No policy server information available." } }, "summary": "Gets information about a Policy Server's configuration, if available.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.18" } }, "/.well-known/matrix/support": { "get": { "description": "Gets server admin contact and support page of the domain.\n\n**NOTE:** \nLike the [well-known discovery URI](https://spec.matrix.org/v1.19/client-server-api/#well-known-uris),\nthis endpoint should be accessed with the hostname of the homeserver's\n[server name](https://spec.matrix.org/v1.19/appendices/#server-name) by making a\nGET request to `https://hostname/.well-known/matrix/support`.\n\n\nNote that this endpoint is not necessarily handled by the homeserver.\nIt may be served by another webserver, used for discovering support\ninformation for the homeserver.", "operationId": "getWellknownSupport", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "contacts": [ { "email_address": "admin@example.org", "matrix_id": "@admin:example.org", "role": "m.role.admin" }, { "email_address": "security@example.org", "role": "m.role.security" } ], "support_page": "https://example.org/support.html" } } }, "schema": { "properties": { "contacts": { "description": "Ways to contact the server administrator.\n\nAt least one of `contacts` or `support_page` is required.\nIf only `contacts` is set, it must contain at least one\nitem.", "items": { "description": "A way to contact the server administrator.", "example": { "email_address": "admin@example.org", "matrix_id": "@admin:example.org", "role": "m.role.admin" }, "properties": { "email_address": { "description": "An email address to reach the administrator.\n\nAt least one of `matrix_id` or `email_address` is\nrequired.", "format": "email", "type": "string" }, "matrix_id": { "description": "A [Matrix User ID](https://spec.matrix.org/v1.19/appendices/#user-identifiers)\nrepresenting the administrator.\n\nIt could be an account registered on a different\nhomeserver so the administrator can be contacted\nwhen the homeserver is down.\n\nAt least one of `matrix_id` or `email_address` is\nrequired.", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "role": { "description": "An informal description of what the contact methods\nare used for.\n\n`m.role.admin` is a catch-all role for any queries\nand `m.role.security` is intended for sensitive\nrequests.\n\nUnspecified roles are permitted through the use of\n[Namespaced Identifiers](https://spec.matrix.org/v1.19/appendices/#common-namespaced-identifier-grammar).", "enum": [ "m.role.admin", "m.role.security" ], "type": "string" } }, "required": [ "role" ], "title": "Contact", "type": "object" }, "type": "array" }, "support_page": { "description": "The URL of a page to give users help specific to the\nhomeserver, like extra login/registration steps.\n\nAt least one of `contacts` or `support_page` is required.", "example": "https://example.org/support.html", "format": "uri", "type": "string" } }, "type": "object" } } }, "description": "Server support information." }, "404": { "description": "No server support information available." } }, "summary": "Gets homeserver contacts and support details.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.10" } }, "/_matrix/client/v1/admin/lock/{userId}": { "get": { "description": "Gets information about the locked status of a particular server-local user.\n\nThe user calling this endpoint MUST be a server admin.\n\nIn order to prevent user enumeration, servers MUST ensure that authorisation is checked\nprior to trying to do account lookups.", "operationId": "getAdminLockUser", "parameters": [ { "description": "The user to look up.", "example": "@peter:rabbit.rocks", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "locked": true } } }, "schema": { "properties": { "locked": { "description": "Whether the target account is locked.", "type": "boolean" } }, "required": [ "locked" ], "type": "object" } } }, "description": "The lookup was successful." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "User does not belong to the local server." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Requesting user is not a server administrator." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The requesting user is not a server administrator, or the target user is another\nadministrator. The errcode is `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "User 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" ], "title": "Error", "type": "object" } } }, "description": "The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets information about the locked status of a particular user.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.18" }, "put": { "description": "Sets the locked status of a particular server-local user.\n\nThe user calling this endpoint MUST be a server admin. The client SHOULD check that the user\nis allowed to lock other users at the [`GET /capabilities`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3capabilities)\nendpoint prior to using this endpoint.\n\nIn order to prevent user enumeration, servers MUST ensure that authorisation is checked\nprior to trying to do account lookups.", "operationId": "setAdminLockUser", "parameters": [ { "description": "The user to change the locked status of.", "example": "@peter:rabbit.rocks", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "request": { "value": { "locked": true } } }, "schema": { "properties": { "locked": { "description": "Whether to lock the target account.", "example": true, "type": "boolean" } }, "required": [ "locked" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "locked": true } } }, "schema": { "properties": { "locked": { "description": "Whether the target account is locked.", "example": true, "type": "boolean" } }, "required": [ "locked" ], "type": "object" } } }, "description": "The action was successful." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "User does not belong to the local server." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Requesting user is not a server administrator." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The requesting user is not a server administrator, is trying to lock their own\naccount, or the target user is another administrator. The errcode is `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "User 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" ], "title": "Error", "type": "object" } } }, "description": "The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set the locked status of a particular user.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.18" } }, "/_matrix/client/v1/admin/suspend/{userId}": { "get": { "description": "Gets information about the suspended status of a particular server-local user.\n\nThe user calling this endpoint MUST be a server admin.\n\nIn order to prevent user enumeration, servers MUST ensure that authorisation is checked\nprior to trying to do account lookups.", "operationId": "getAdminSuspendUser", "parameters": [ { "description": "The user to look up.", "example": "@peter:rabbit.rocks", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "suspended": true } } }, "schema": { "properties": { "suspended": { "description": "Whether the target account is suspended.", "example": true, "type": "boolean" } }, "required": [ "suspended" ], "type": "object" } } }, "description": "The lookup was successful." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "User does not belong to the local server." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Requesting user is not a server administrator." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The requesting user is not a server administrator, or the target user is another\nadministrator. The errcode is `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "User 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" ], "title": "Error", "type": "object" } } }, "description": "The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets information about the suspended status of a particular user.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.18" }, "put": { "description": "Sets the suspended status of a particular server-local user.\n\nThe user calling this endpoint MUST be a server admin. The client SHOULD check that the user\nis allowed to suspend other users at the [`GET /capabilities`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3capabilities)\nendpoint prior to using this endpoint.\n\nIn order to prevent user enumeration, servers MUST ensure that authorisation is checked\nprior to trying to do account lookups.", "operationId": "setAdminSuspendUser", "parameters": [ { "description": "The user to change the suspended status of.", "example": "@peter:rabbit.rocks", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "request": { "value": { "suspended": true } } }, "schema": { "properties": { "suspended": { "description": "Whether to suspend the target account.", "example": true, "type": "boolean" } }, "required": [ "suspended" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "suspended": true } } }, "schema": { "properties": { "suspended": { "description": "Whether the target account is suspended.", "example": true, "type": "boolean" } }, "required": [ "suspended" ], "type": "object" } } }, "description": "The action was successful." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "User does not belong to the local server." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user ID does not belong to the local server. The errcode is `M_INVALID_PARAM`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Requesting user is not a server administrator." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The requesting user is not a server administrator, is trying to suspend their own\naccount, or the target user is another administrator. The errcode is `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "User 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" ], "title": "Error", "type": "object" } } }, "description": "The user ID is not found, or is deactivated. The errcode is `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set the suspended status of a particular user.", "tags": [ "Server administration" ], "x-addedInMatrixVersion": "1.18" } }, "/_matrix/client/v1/appservice/{appserviceId}/ping": { "post": { "description": "This API asks the homeserver to call the\n[`/_matrix/app/v1/ping`](https://spec.matrix.org/v1.19/application-service-api/#post_matrixappv1ping) endpoint on the\napplication service to ensure that the homeserver can communicate\nwith the application service.\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. Additionally, the\nappservice ID in the path must be the same as the appservice whose `as_token`\nis being used.", "operationId": "pingAppservice", "parameters": [ { "description": "The appservice ID of the appservice to ping. This must be the same\nas the appservice whose `as_token` is being used to authenticate the\nrequest.", "example": "telegram", "in": "path", "name": "appserviceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "transaction_id": { "description": "An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call.", "example": "mautrix-go_1683636478256400935_123", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "duration_ms": 123 } } }, "schema": { "properties": { "duration_ms": { "description": "The duration in milliseconds that the\n[`/_matrix/app/v1/ping`](https://spec.matrix.org/v1.19/application-service-api/#post_matrixappv1ping)\nrequest took from the homeserver's point of view.", "type": "integer" } }, "required": [ "duration_ms" ], "type": "object" } } }, "description": "The ping was successful." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_URL_NOT_SET", "error": "Application service doesn't have a URL configured" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Provided access token is not the appservice's as_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" ], "title": "Error", "type": "object" } } }, "description": "The access token used to authenticate the request doesn't belong to an appservice, or belongs to a different appservice than the one in the path. The errcode is `M_FORBIDDEN`." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "body": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}", "errcode": "M_BAD_STATUS", "error": "Ping returned status 401", "status": 401 } } }, "schema": { "description": "A Matrix-level Error", "properties": { "body": { "description": "The HTTP response body returned by the appservice.", "example": "{\"errcode\": \"M_UNKNOWN_TOKEN\"}", "type": "string" }, "errcode": { "description": "An error code.", "enum": [ "M_BAD_STATUS", "M_CONNECTION_FAILED" ], "type": "string" }, "error": { "description": "A human-readable error message.", "example": "Ping returned status 401", "type": "string" }, "status": { "description": "The HTTP status code returned by the appservice.", "example": 401, "type": "integer" } }, "required": [ "errcode" ], "title": "Error", "type": "object" } } }, "description": "The application service returned a bad status, or the connection failed.\nThe errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`.\n\nFor bad statuses, the response may include `status` and `body`\nfields containing the HTTP status code and response body text\nrespectively to aid with debugging." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_CONNECTION_TIMEOUT", "error": "Connection to application service timed out" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`." } }, "security": [ { "appserviceAccessTokenQuery": [] }, { "appserviceAccessTokenBearer": [] } ], "summary": "Ask the homeserver to ping the application service to ensure the connection works.", "x-addedInMatrixVersion": "1.7" } }, "/_matrix/client/v1/auth_metadata": { "get": { "description": "Gets the OAuth 2.0 authorisation server metadata, as defined in\n[RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the\nendpoint URLs and the supported parameters that can be used by the\nclients.\n\nThis endpoint definition includes only the fields that are meaningful in\nthe context of the Matrix specification. The full list of possible\nfields is available in the [OAuth Authorisation Server Metadata\nregistry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),\nand normative definitions of them are available in their respective\nRFCs.\n\n**NOTE:** \nThe authorisation server metadata is relatively large and may change\nover time. Clients should:\n\n- Cache the metadata appropriately based on HTTP caching headers\n- Refetch the metadata if it is stale\n", "operationId": "getAuthMetadata", "responses": { "200": { "content": { "application/json": { "schema": { "example": { "account_management_actions_supported": [ "org.matrix.profile", "org.matrix.devices_list", "org.matrix.device_view", "org.matrix.device_delete", "org.matrix.account_deactivate", "org.matrix.cross_signing_reset" ], "account_management_uri": "https://account.example.com/manage", "authorization_endpoint": "https://account.example.com/oauth2/auth", "code_challenge_methods_supported": [ "S256" ], "device_authorization_endpoint": "https://account.example.com/oauth2/device", "grant_types_supported": [ "authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code" ], "issuer": "https://account.example.com/", "registration_endpoint": "https://account.example.com/oauth2/clients/register", "response_modes_supported": [ "query", "fragment" ], "response_types_supported": [ "code" ], "revocation_endpoint": "https://account.example.com/oauth2/revoke", "token_endpoint": "https://account.example.com/oauth2/token" }, "properties": { "account_management_actions_supported": { "description": "List of actions that the account management URL supports.\n\nThis is an extension [defined in this specification](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-account-management).", "items": { "description": "An action that the account management URL supports.", "enum": [ "org.matrix.profile", "org.matrix.devices_list", "org.matrix.device_view", "org.matrix.device_delete", "org.matrix.account_deactivate", "org.matrix.cross_signing_reset" ], "type": "string" }, "type": "array", "x-addedInMatrixVersion": "1.18" }, "account_management_uri": { "description": "The URL where the user is able to access the account management capabilities\nof the homeserver.\n\nThis is an extension [defined in this specification](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-account-management).", "format": "uri", "type": "string", "x-addedInMatrixVersion": "1.18" }, "authorization_endpoint": { "description": "URL of the authorisation endpoint, necessary to use the authorisation code\ngrant.", "format": "uri", "type": "string" }, "code_challenge_methods_supported": { "description": "List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods\nthat the server supports at the authorisation endpoint.\n\nThis array MUST contain at least the `S256` value, for improved security in\nthe authorisation code grant.", "items": { "description": "A PKCE code challenge method that the server supports.", "type": "string" }, "type": "array" }, "device_authorization_endpoint": { "description": "URL of the device authorisation endpoint, as defined in\n[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use\nthe [device authorisation grant](https://spec.matrix.org/v1.19/client-server-api/#device-authorisation-grant).", "format": "uri", "type": "string", "x-addedInMatrixVersion": "1.18" }, "grant_types_supported": { "description": "List of OAuth 2.0 grant type strings that the server supports at the token\nendpoint.\n\nThis array MUST contain at least the `authorization_code` and `refresh_token`\nvalues, for clients to be able to use the authorisation code grant and refresh\ntoken grant, respectively.\n\n**[Added in `v1.18`]** It MAY also contain\n`urn:ietf:params:oauth:grant-type:device_code` to indicate support for the\n[device authorisation grant](https://spec.matrix.org/v1.19/client-server-api/#device-authorisation-grant).", "items": { "description": "A grant type that the server supports.", "type": "string" }, "type": "array" }, "issuer": { "description": "The authorisation server's issuer identifier, which is a URL that uses the\n`https` scheme and has no query or fragment components.\n\nThis is not used in the context of the Matrix specification, but is required\nby [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).", "format": "uri", "type": "string" }, "prompt_values_supported": { "description": "List of OpenID Connect prompt values that the server supports at the\nauthorisation endpoint.\n\nOnly the `create` value defined in [Initiating User Registration via OpenID\nConnect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is\nsupported, for a client to signal to the server that the user desires to\nregister a new account.", "items": { "description": "A prompt value that the server supports.", "type": "string" }, "type": "array" }, "registration_endpoint": { "description": "URL of the client registration endpoint, necessary to perform dynamic\nregistration of a client.", "format": "uri", "type": "string" }, "response_modes_supported": { "description": "List of OAuth 2.0 response mode strings that the server supports at the\nauthorisation endpoint.\n\nThis array MUST contain at least the `query` and `fragment` values, for\nimproved security in the authorisation code grant.", "items": { "description": "A response mode that the server supports.", "type": "string" }, "type": "array" }, "response_types_supported": { "description": "List of OAuth 2.0 response type strings that the server supports at the\nauthorisation endpoint.\n\nThis array MUST contain at least the `code` value, for clients to be able to\nuse the authorisation code grant.", "items": { "description": "A response type that the server supports.", "type": "string" }, "type": "array" }, "revocation_endpoint": { "description": "URL of the revocation endpoint, necessary to log out a client by invalidating\nits access and refresh tokens.", "format": "uri", "type": "string" }, "token_endpoint": { "description": "URL of the token endpoint, used by the grants.", "format": "uri", "type": "string" } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "revocation_endpoint", "registration_endpoint", "response_types_supported", "grant_types_supported", "response_modes_supported", "code_challenge_methods_supported" ], "type": "object" } } }, "description": "The OAuth 2.0 authorisation server metadata." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_UNRECOGNIZED", "error": "Legacy authentication is in use on this homeserver." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "With `M_UNRECOGNIZED`: the homeserver does not support the OAuth 2.0 API.\n(See [Authentication API discovery](https://spec.matrix.org/v1.19/client-server-api/#authentication-api-discovery).)" } }, "summary": "Get the OAuth 2.0 authorisation server metadata.", "tags": [ "Session management" ] } }, "/_matrix/client/v1/login/get_token": { "post": { "description": "Optional endpoint - the server is not required to implement this endpoint if it does not\nintend to use or support this functionality.\n\nThis API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api).\n\nAn already-authenticated client can call this endpoint to generate a single-use, time-limited,\ntoken for an unauthenticated client to log in with, becoming logged in as the same user which\ncalled this endpoint. The unauthenticated client uses the generated token in a `m.login.token`\nlogin flow with the homeserver.\n\nClients, both authenticated and unauthenticated, might wish to hide user interface which exposes\nthis feature if the server is not offering it. Authenticated clients can check for support on\na per-user basis with the [`m.get_login_token`](https://spec.matrix.org/v1.19/client-server-api/#mget_login_token-capability) capability,\nwhile unauthenticated clients can detect server support by looking for an `m.login.token` login\nflow with `get_login_token: true` on [`GET /login`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3login).\n\nIn v1.7 of the specification, transmission of the generated token to an unauthenticated client is\nleft as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906)\nmight standardise a way to transmit the token between clients.\n\nThe generated token MUST only be valid for a single login, enforced by the server. Clients which\nintend to log in multiple devices must generate a token for each.\n\nWith other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt\nfor verification if the session recently passed UIA. For this endpoint, servers MUST always re-prompt\nthe user for verification to ensure explicit consent is gained for each additional client.\n\nServers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum\nof 1 request per minute.", "operationId": "generateLoginToken", "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the user-interactive authentication API." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "expires_in_ms": 120000, "login_token": "" } } }, "schema": { "properties": { "expires_in_ms": { "description": "The time remaining in milliseconds until the homeserver will no longer accept the token. `120000`\n(2 minutes) is recommended as a default.", "type": "integer" }, "login_token": { "description": "The login token for the `m.login.token` login flow.", "type": "string" } }, "required": [ "login_token", "expires_in_ms" ], "type": "object" } } }, "description": "The login token an unauthenticated client can use to log in as the requesting user." }, "400": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "description": "The request was malformed, or the user does not have an ability to generate tokens for their devices,\nas implied by the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api).\n\nClients should verify whether the user has an ability to call this endpoint with the\n[`m.get_login_token`](https://spec.matrix.org/v1.19/client-server-api/#mget_login_token-capability) capability." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Optional endpoint to generate a single-use, time-limited, `m.login.token` token.", "tags": [ "Session management" ], "x-addedInMatrixVersion": "1.7" } }, "/_matrix/client/v1/media/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:** \nBoth 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.\n", "operationId": "getConfigAuthed", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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" } } }, "description": "The public content repository configuration for the matrix server." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the configuration for the content repository.", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.11" } }, "/_matrix/client/v1/media/download/{serverName}/{mediaId}": { "get": { "description": "**NOTE:** \nClients SHOULD NOT generate or use URLs which supply the access token in\nthe query string. These URLs may be copied by users verbatim and provided\nin a chat message to another user, disclosing the sender's access token.\n\n\nClients MAY be redirected using the 307/308 responses below to download\nthe request object. This is typical when the homeserver uses a Content\nDelivery Network (CDN).", "operationId": "getContentAuthed", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "**Required.** The bytes for the uploaded file." } } }, "description": "The content that was previously uploaded.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be one of `inline` or `attachment`,\nand SHOULD contain a file name.\n\nIf the `Content-Type` is allowed in the [restrictions for serving\ninline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nservers SHOULD use `inline`, otherwise they SHOULD use\n`attachment`.\n\nIf the upload was made with a `filename`, this header MUST\ncontain the same `filename`. Otherwise, `filename` is excluded\nfrom the header. If the media being downloaded is remote, the\nremote server's `filename` in the `Content-Disposition` header\nis used as the `filename` instead. When the header is not\nsupplied, or does not supply a `filename`, the local download\nresponse does not include a `filename`.\n", "required": true, "schema": { "example": "inline; filename=\"filename.jpg\"", "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required." } }, "Content-Type": { "description": "The content type of the file that was previously uploaded.\n\nThe server MUST return a `Content-Type` which is either exactly the same\nas the original upload, or reasonably close. The bounds of \"reasonable\"\nare:\n\n* Adding a charset to `text/*` content types.\n* Detecting HTML and using `text/html` instead of `text/plain`.\n* Using `application/octet-stream` when the server determines the\n content type is obviously wrong. For example, an encrypted file being\n claimed as `image/png`.\n* Returning `application/octet-stream` when the media has an\n unknown/unprovided `Content-Type`. For example, being uploaded before\n the server tracked content types or when the remote server is\n non-compliantly omitting the header entirely.\n\nActions not in the spirit of the above are not considered \"reasonable\".\n", "required": true, "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`,\nand the behaviour to compute its value was clarified.\n" } } } }, "307": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The content is too large for the server to serve." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Download content from the content repository.", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.11" } }, "/_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}": { "get": { "description": "This will download content from the content repository (same as\nthe previous endpoint) but replaces the target file name with the one\nprovided by the caller.\n\n**NOTE:** \nClients SHOULD NOT generate or use URLs which supply the access token in\nthe query string. These URLs may be copied by users verbatim and provided\nin a chat message to another user, disclosing the sender's access token.\n\n\nClients MAY be redirected using the 307/308 responses below to download\nthe request object. This is typical when the homeserver uses a Content\nDelivery Network (CDN).", "operationId": "getContentOverrideNameAuthed", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "A filename to give in the `Content-Disposition` header.", "example": "filename.jpg", "in": "path", "name": "fileName", "required": true, "schema": { "type": "string" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "**Required.** The bytes for the uploaded file." } } }, "description": "The content that was previously uploaded.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be one of `inline` or `attachment`,\nand MUST contain the file name requested in the path.\n\nIf the `Content-Type` is allowed in the [restrictions for serving\ninline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nservers SHOULD use `inline`, otherwise they SHOULD use\n`attachment`.\n", "required": true, "schema": { "example": "inline; filename=\"filename.jpg\"", "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required." } }, "Content-Type": { "description": "The content type of the file that was previously uploaded.\n\nThe server MUST return a `Content-Type` which is either exactly the same\nas the original upload, or reasonably close. The bounds of \"reasonable\"\nare:\n\n* Adding a charset to `text/*` content types.\n* Detecting HTML and using `text/html` instead of `text/plain`.\n* Using `application/octet-stream` when the server determines the\n content type is obviously wrong. For example, an encrypted file being\n claimed as `image/png`.\n* Returning `application/octet-stream` when the media has an\n unknown/unprovided `Content-Type`. For example, being uploaded before\n the server tracked content types or when the remote server is\n non-compliantly omitting the header entirely.\n\nActions not in the spirit of the above are not considered \"reasonable\".\n", "required": true, "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`,\nand the behaviour to compute its value was clarified.\n" } } } }, "307": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The content is too large for the server to serve." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Download content from the content repository overriding the file name.", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.11" } }, "/_matrix/client/v1/media/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:** \nClients should consider avoiding this endpoint for URLs posted in encrypted\nrooms. Encrypted rooms often contain more sensitive information the users\ndo not want to share with the homeserver, and this can mean that the URLs\nbeing shared should also not be shared with the homeserver.\n", "operationId": "getUrlPreviewAuthed", "parameters": [ { "description": "The URL to get a preview of.", "example": "https://matrix.org", "in": "query", "name": "url", "required": true, "schema": { "format": "uri", "type": "string" } }, { "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.", "example": 1510610716656, "in": "query", "name": "ts", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "additionalProperties": { "description": "Additional properties as per the [OpenGraph](https://ogp.me/) protocol." }, "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](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image.", "format": "uri", "type": "string" } }, "type": "object" } } }, "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](https://ogp.me/) are\ndescribed here." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get information about a URL for a client", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.11" } }, "/_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}": { "get": { "description": "Download a thumbnail of content from the content repository.\nSee the [Thumbnails](https://spec.matrix.org/v1.19/client-server-api/#thumbnails) section for more information.\n\n**NOTE:** \nClients SHOULD NOT generate or use URLs which supply the access token in\nthe query string. These URLs may be copied by users verbatim and provided\nin a chat message to another user, disclosing the sender's access token.\n\n\nClients MAY be redirected using the 307/308 responses below to download\nthe request object. This is typical when the homeserver uses a Content\nDelivery Network (CDN).", "operationId": "getContentThumbnailAuthed", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "The *desired* width of the thumbnail. The actual thumbnail may be\nlarger than the size specified.", "example": 64, "in": "query", "name": "width", "required": true, "schema": { "type": "integer" } }, { "description": "The *desired* height of the thumbnail. The actual thumbnail may be\nlarger than the size specified.", "example": 64, "in": "query", "name": "height", "required": true, "schema": { "type": "integer" } }, { "description": "The desired resizing method. See the [Thumbnails](https://spec.matrix.org/v1.19/client-server-api/#thumbnails)\nsection for more information.", "example": "scale", "in": "query", "name": "method", "schema": { "enum": [ "crop", "scale" ], "type": "string" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" }, { "description": "Indicates preference for an animated thumbnail from the server, if possible. Animated\nthumbnails typically use the content types `image/gif`, `image/png` (with APNG format),\n`image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`\ncontent types.\n\nWhen `true`, the server SHOULD return an animated thumbnail if possible and supported.\nWhen `false`, the server MUST NOT return an animated thumbnail. For example, returning a\nstatic `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT\nreturn an animated thumbnail.\n\nServers SHOULD prefer to return `image/webp` thumbnails when supporting animation.\n\nWhen `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the\nserver SHOULD behave as though `animated` is `false`.\n", "example": false, "in": "query", "name": "animated", "required": false, "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.11" } ], "responses": { "200": { "content": { "image/apng": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } }, "image/gif": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } }, "image/jpeg": { "schema": { "description": "**Required.** The bytes for the thumbnail." } }, "image/png": { "schema": { "description": "**Required.** The bytes for the thumbnail. The thumbnail MAY use an animated\nformat if `animated=true`.\n", "x-changedInMatrixVersion": { "1.11": "The PNG may be of the APNG variety if animation is supported and requested." } } }, "image/webp": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } } }, "description": "A thumbnail of the requested content.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`).\n\nServers should note the [Content-Type restrictions for serving inline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nas these limitations imply which formats should be used for thumbnail generation.\n", "required": true, "schema": { "example": "inline; filename=\"thumbnail.png\"", "type": "string" }, "x-addedInMatrixVersion": "1.12" }, "Content-Type": { "description": "The content type of the thumbnail.", "required": true, "schema": { "enum": [ "image/jpeg", "image/png", "image/apng", "image/gif", "image/webp" ], "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`.\n" } } } }, "307": { "description": "A redirect to the thumbnail of the requested content.", "headers": { "Location": { "description": "The URL of the thumbnail content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the thumbnail of the requested content.", "headers": { "Location": { "description": "The URL of the thumbnail content.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "413": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The local content is too large for the server to thumbnail." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The remote content is too large for the server to thumbnail." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Download a thumbnail of content from the content repository", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.11" } }, "/_matrix/client/v1/mutual_rooms": { "get": { "description": "Get the list of rooms that the user shares with another user. The\nserver will return a list of room IDs that the user shares with the\nspecified `user_id`.", "operationId": "getMutualRooms", "parameters": [ { "description": "The MXID of the user to check for mutual rooms with.", "example": "@alice:example.com", "in": "query", "name": "user_id", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "A pagination token from a previous result. This should be a `next_batch` result from\na previous call to this endpoint. If not provided, the server will return the first\nbatch of results.", "example": "next_batch_token", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of such rooms. This is the total count even if the response is\nbatched and `joined` doesn't include all rooms. This MAY be inaccurate\nif the server is unable to calculate the exact number of rooms.", "example": 1, "type": "integer" }, "joined": { "description": "A list of room IDs where both the authenticated user and `user_id` have a\nmembership of type `join`.", "items": { "example": "!OGEhHVWSdvArJzumhm:matrix.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "next_batch": { "description": "A pagination token to retrieve the next batch of results. This will be absent\nif there are no more results to return.", "example": "next_batch_token", "type": "string" } }, "required": [ "joined", "count" ], "type": "object" } } }, "description": "A list of room IDs that the user shares with the specified user.\nIf the provided `user_id` is not a valid user, the server MUST return an empty list of rooms." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "The user ID provided was invalid" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "Part of the request was invalid. The `from` token provided was invalid or expired,\nthe `user_id` parameter was missing, [non-compliant](https://spec.matrix.org/v1.19/appendices/#historical-user-ids),\nor was the sender's own user ID." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the list of rooms that the user shares with another user.", "tags": [ "Mutual Rooms" ] } }, "/_matrix/client/v1/register/m.login.registration_token/validity": { "get": { "description": "Queries the server to determine if a given registration token is still\nvalid at the time of request. This is a point-in-time check where the\ntoken might still expire by the time it is used.\n\nServers should be sure to rate limit this endpoint to avoid brute force\nattacks.", "operationId": "registrationTokenValidity", "parameters": [ { "description": "The token to check validity of.", "example": "fBVFdqVE", "in": "query", "name": "token", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "valid": true } } }, "schema": { "properties": { "valid": { "description": "True if the token is still valid, false otherwise. This should\nadditionally be false if the token is not a recognised token by\nthe server.", "type": "boolean" } }, "required": [ "valid" ], "type": "object" } } }, "description": "The check has a result." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Registration is not enabled on this homeserver." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not permit registration and thus all tokens are\nconsidered invalid." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "summary": "Query if a given registration token is still valid.", "tags": [ "Account management" ], "x-addedInMatrixVersion": "1.2" } }, "/_matrix/client/v1/room_summary/{roomIdOrAlias}": { "get": { "description": "Retrieves a summary for a room.\n\nClients should note that requests for rooms where the user's membership\nis `invite` or `knock` might yield outdated, partial or even no data\nsince the server may not have access to the current state of the room.\n\nServers MAY allow unauthenticated access to this API if at least one of\nthe following conditions holds true:\n\n- The room has a [join rule](#mroomjoin_rules) of `public`, `knock` or\n `knock_restricted`.\n- The room has a `world_readable` [history visibility](#room-history-visibility).\n\nServers should consider rate limiting requests that require a federation\nrequest more heavily if the client is unauthenticated.", "operationId": "getRoomSummary", "parameters": [ { "description": "The room identifier or alias to summarise.", "example": "#monkeys:matrix.org", "in": "path", "name": "roomIdOrAlias", "required": true, "schema": { "oneOf": [ { "format": "mx-room-id", "pattern": "^!", "type": "string" }, { "format": "mx-room-alias", "pattern": "^#", "type": "string" } ] } }, { "description": "The servers to attempt to request the summary from when\nthe local server cannot generate it (for instance, because\nit has no local user in the room).", "example": [ "matrix.org", "elsewhere.ca" ], "in": "query", "name": "via", "schema": { "items": { "format": "mx-server-name", "type": "string" }, "type": "array" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", "encryption": "m.megolm.v1.aes-sha2", "guest_can_join": false, "join_rule": "public", "membership": "invite", "name": "CHEESE", "num_joined_members": 37, "room_id": "!ol19s:bleecker.street", "room_type": "m.space", "room_version": "9001", "topic": "Tasty tasty cheese", "world_readable": true } } }, "schema": { "allOf": [ { "allOf": [ { "properties": { "avatar_url": { "description": "The URL for the room's avatar, if one is set.", "example": "mxc://example.org/abcdef", "format": "uri", "type": "string" }, "canonical_alias": { "description": "The canonical alias of the room, if any.", "example": "#general:example.org", "format": "mx-room-alias", "pattern": "^#", "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.", "example": true, "type": "boolean" }, "join_rule": { "description": "The room's join rule. When not present, the room is assumed to\nbe `public`.", "example": "public", "type": "string" }, "name": { "description": "The name of the room, if any.", "example": "General Chat", "type": "string" }, "num_joined_members": { "description": "The number of members joined to the room.", "example": 42, "type": "integer" }, "room_id": { "description": "The ID of the room.", "example": "!abcdefg:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "topic": { "description": "The plain text topic of the room. Omitted if no `text/plain` mimetype\nexists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).", "example": "All things general", "type": "string" }, "world_readable": { "description": "Whether the room may be viewed by users without joining.", "example": false, "type": "boolean" } }, "required": [ "room_id", "num_joined_members", "world_readable", "guest_can_join" ], "title": "PublishedRoomsChunk", "type": "object" }, { "properties": { "allowed_room_ids": { "description": "If the room is a [restricted room](https://spec.matrix.org/v1.19/server-server-api/#restricted-rooms), these are the room IDs which\nare specified by the join rules. Empty or omitted otherwise.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "encryption": { "description": "The encryption algorithm to be used to encrypt messages sent in the\nroom.", "enum": [ "m.megolm.v1.aes-sha2" ], "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "room_version": { "description": "The version of the room.", "type": "string" } }, "type": "object" } ], "title": "RoomSummary", "type": "object" }, { "properties": { "membership": { "description": "The membership state of the user if the user is joined to the room. Absent\nif the API was called unauthenticated.", "enum": [ "invite", "join", "knock", "leave", "ban" ], "type": "string" } }, "type": "object" } ], "description": "A summary of the room." } } }, "description": "A summary of the room." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Room 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" ], "title": "Error", "type": "object" } } }, "description": "The room could not be found." } }, "security": [ { "signedRequest": [] } ], "summary": "Retrieves a summary for a room.", "x-addedInMatrixVersion": "1.15" } }, "/_matrix/client/v1/rooms/{roomId}/hierarchy": { "get": { "description": "Paginates over the space tree in a depth-first manner to locate child rooms of a given space.\n\nWhere a child room is unknown to the local server, federation is used to fill in the details.\nThe servers listed in the `via` array should be contacted to attempt to fill in missing rooms.\n\nOnly [`m.space.child`](https://spec.matrix.org/v1.19/client-server-api/#mspacechild) state events of the room are considered.\nInvalid child rooms and parent events are not covered by this endpoint.", "operationId": "getSpaceHierarchy", "parameters": [ { "description": "The room ID of the space to get a hierarchy for.", "example": "!space:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "Optional (default `false`) flag to indicate whether or not the server should only consider\nsuggested rooms. Suggested rooms are annotated in their [`m.space.child`](https://spec.matrix.org/v1.19/client-server-api/#mspacechild)\nevent contents.", "example": true, "in": "query", "name": "suggested_only", "schema": { "type": "boolean" } }, { "description": "Optional limit for the maximum number of rooms to include per response. Must be an integer\ngreater than zero.\n\nServers should apply a default value, and impose a maximum value to avoid resource exhaustion.", "example": 20, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "Optional limit for how far to go into the space. Must be a non-negative integer.\n\nWhen reached, no further child rooms will be returned.\n\nServers should apply a default value, and impose a maximum value to avoid resource exhaustion.", "example": 5, "in": "query", "name": "max_depth", "schema": { "type": "integer" } }, { "description": "A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot\nbe changed from the first request.", "example": "next_batch_token", "in": "query", "name": "from", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "next_batch": "next_batch_token", "rooms": [ { "avatar_url": "mxc://example.org/abcdef", "canonical_alias": "#general:example.org", "children_state": [ { "content": { "via": [ "example.org" ] }, "origin_server_ts": 1629413349153, "sender": "@alice:example.org", "state_key": "!a:example.org", "type": "m.space.child" } ], "guest_can_join": false, "join_rule": "public", "name": "The First Space", "num_joined_members": 42, "room_id": "!space:example.org", "room_type": "m.space", "topic": "No other spaces were created first, ever", "world_readable": true } ] } } }, "schema": { "properties": { "next_batch": { "description": "A token to supply to `from` to keep paginating the responses. Not present when there are\nno further results.", "type": "string" }, "rooms": { "description": "The rooms for the current page, with the current filters.\n\nThe server should return any rooms where at least one of the following conditions is true:\n\n* The requesting user is currently a member (their [room membership](#room-membership) is `join`).\n* The requesting user already has permission to join, i.e. one of the following:\n * The user's room membership is `invite`.\n * The room's [join rules](#mroomjoin_rules) are set to `public`.\n * The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions.\n* The room is \"knockable\" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings).\n* The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.", "items": { "allOf": [ { "allOf": [ { "properties": { "avatar_url": { "description": "The URL for the room's avatar, if one is set.", "example": "mxc://example.org/abcdef", "format": "uri", "type": "string" }, "canonical_alias": { "description": "The canonical alias of the room, if any.", "example": "#general:example.org", "format": "mx-room-alias", "pattern": "^#", "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.", "example": true, "type": "boolean" }, "join_rule": { "description": "The room's join rule. When not present, the room is assumed to\nbe `public`.", "example": "public", "type": "string" }, "name": { "description": "The name of the room, if any.", "example": "General Chat", "type": "string" }, "num_joined_members": { "description": "The number of members joined to the room.", "example": 42, "type": "integer" }, "room_id": { "description": "The ID of the room.", "example": "!abcdefg:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "topic": { "description": "The plain text topic of the room. Omitted if no `text/plain` mimetype\nexists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).", "example": "All things general", "type": "string" }, "world_readable": { "description": "Whether the room may be viewed by users without joining.", "example": false, "type": "boolean" } }, "required": [ "room_id", "num_joined_members", "world_readable", "guest_can_join" ], "title": "PublishedRoomsChunk", "type": "object" }, { "properties": { "allowed_room_ids": { "description": "If the room is a [restricted room](https://spec.matrix.org/v1.19/server-server-api/#restricted-rooms), these are the room IDs which\nare specified by the join rules. Empty or omitted otherwise.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "encryption": { "description": "The encryption algorithm to be used to encrypt messages sent in the\nroom.", "enum": [ "m.megolm.v1.aes-sha2" ], "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "room_version": { "description": "The version of the room.", "type": "string" } }, "type": "object" } ], "title": "RoomSummary", "type": "object" }, { "properties": { "allowed_room_ids": { "x-addedInMatrixVersion": "1.15" }, "children_state": { "description": "The [`m.space.child`](https://spec.matrix.org/v1.19/client-server-api/#mspacechild) events of the space-room, represented\nas [Stripped State Events](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) with an added `origin_server_ts` key.\n\nIf the room is not a space-room, this should be empty.", "items": { "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "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.", "format": "mx-user-id", "pattern": "^@", "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": "StrippedStateEvent", "type": "object" }, { "properties": { "origin_server_ts": { "description": "The `origin_server_ts` for the event.", "format": "int64", "type": "integer" } }, "required": [ "origin_server_ts" ], "title": "StrippedChildStateEvent", "type": "object" } ] }, "type": "array" }, "encryption": { "x-addedInMatrixVersion": "1.15" }, "room_type": { "x-addedInMatrixVersion": "1.4" }, "room_version": { "x-addedInMatrixVersion": "1.15" } }, "required": [ "children_state" ], "title": "SpaceHierarchyRoomsChunk", "type": "object" } ] }, "type": "array" } }, "required": [ "rooms" ], "type": "object" } } }, "description": "A portion of the space tree, starting at the provided room ID." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "suggested_only and max_depth cannot change on paginated requests" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The request was invalid in some way. A meaningful `errcode`\nand description error text will be returned. Example reasons for rejection are:\n\n- The `from` token is unknown to the server.\n- `suggested_only` or `max_depth` changed during pagination." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "You are not allowed to view 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" ], "title": "Error", "type": "object" } } }, "description": "The user cannot view or peek on the room. A meaningful `errcode`\nand description error text will be returned. Example reasons for rejection are:\n\n- The room is not set up for peeking.\n- The user has been banned from the room.\n- The room does not exist." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve a portion of a space tree.", "tags": [ "Spaces" ], "x-addedInMatrixVersion": "1.2" } }, "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}": { "get": { "description": "Retrieve all of the child events for a given parent event.\n\nNote that when paginating the `from` token should be \"after\" the `to` token in\nterms of topological ordering, because it is only possible to paginate \"backwards\"\nthrough events, starting at `from`.\n\nFor example, passing a `from` token from page 2 of the results, and a `to` token\nfrom page 1, would return the empty set. The caller can use a `from` token from\npage 1 and a `to` token from page 2 to paginate over the same range, however.", "operationId": "getRelatingEvents", "parameters": [ { "description": "The ID of the room containing the parent event.", "example": "!636q39766251:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The ID of the parent event whose child events are to be returned.", "example": "$asfDuShaf7Gafaw", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, { "description": "The pagination token to start returning results from. If not supplied, results\nstart at the most recent topological event known to the server.\n\nCan be a `next_batch` or `prev_batch` token from a previous call, or a returned\n`start` token from [`/messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync).", "example": "page2_token", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The pagination token to stop returning results at. If not supplied, results\ncontinue up to `limit` or until there are no more events.\n\nLike `from`, this can be a previous token from a prior call to this endpoint\nor from `/messages` or `/sync`.", "example": "page3_token", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "The maximum number of results to return in a single `chunk`. The server can\nand should apply a maximum value to this parameter to avoid large responses.\n\nSimilarly, the server should apply a default value when not supplied.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Optional (default `b`) direction to return events from. If this is set to `f`, events\nwill be returned in chronological order starting at `from`. If it\nis set to `b`, events will be returned in *reverse* chronological\norder, again starting at `from`.", "in": "query", "name": "dir", "schema": { "enum": [ "b", "f" ], "type": "string" }, "x-addedInMatrixVersion": "1.4" }, { "description": "Whether to additionally include events which only relate indirectly to the\ngiven event, i.e. events related to the given event via two or more direct relationships.\n\nIf set to `false`, only events which have a direct relation with the given\nevent will be included.\n\nIf set to `true`, events which have an indirect relation with the given event\nwill be included additionally up to a certain depth level. Homeservers SHOULD traverse\nat least 3 levels of relationships. Implementations MAY perform more but MUST be careful\nto not infinitely recurse.\n\nThe default value is `false`.", "in": "query", "name": "recurse", "required": false, "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.10" } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "m.relates_to": { "event_id": "$asfDuShaf7Gafaw", "rel_type": "org.example.my_relation" } }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:matrix.org", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "next_batch": "page2_token", "prev_batch": "page1_token" } } }, "schema": { "allOf": [ { "properties": { "next_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans there are no more results to fetch and the client should stop paginating.", "type": "string" }, "prev_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans this is the start of the result set, i.e. this is the first batch/page.", "type": "string" }, "recursion_depth": { "description": "If the `recurse` parameter was supplied by the client, this response field is\nmandatory and gives the actual depth to which the server recursed. If the client\ndid not specify the `recurse` parameter, this field must be absent.", "type": "integer" } }, "type": "object" }, { "properties": { "chunk": { "description": "The child events of the requested event, ordered topologically most-recent first.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "title": "ChildEventsChunk", "type": "array" } }, "required": [ "chunk" ], "type": "object" } ] } } }, "description": "The paginated child events which point to the parent. If no events are\npointing to the parent or the pagination yields no results, an empty `chunk`\nis returned." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Event 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" ], "title": "Error", "type": "object" } } }, "description": "The parent event was not found or the user does not have permission to read\nthis event (it might be contained in history that is not accessible to the user)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the child events for a given parent event.", "tags": [ "Event relationships" ] } }, "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}/{relType}": { "get": { "description": "Retrieve all of the child events for a given parent event which relate to the parent\nusing the given `relType`.\n\nNote that when paginating the `from` token should be \"after\" the `to` token in\nterms of topological ordering, because it is only possible to paginate \"backwards\"\nthrough events, starting at `from`.\n\nFor example, passing a `from` token from page 2 of the results, and a `to` token\nfrom page 1, would return the empty set. The caller can use a `from` token from\npage 1 and a `to` token from page 2 to paginate over the same range, however.", "operationId": "getRelatingEventsWithRelType", "parameters": [ { "description": "The ID of the room containing the parent event.", "example": "!636q39766251:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The ID of the parent event whose child events are to be returned.", "example": "$asfDuShaf7Gafaw", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, { "description": "The [relationship type](https://spec.matrix.org/v1.19/client-server-api/#relationship-types) to search for.", "example": "org.example.my_relation", "in": "path", "name": "relType", "required": true, "schema": { "type": "string" } }, { "description": "The pagination token to start returning results from. If not supplied, results\nstart at the most recent topological event known to the server.\n\nCan be a `next_batch` or `prev_batch` token from a previous call, or a returned\n`start` token from [`/messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync).", "example": "page2_token", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The pagination token to stop returning results at. If not supplied, results\ncontinue up to `limit` or until there are no more events.\n\nLike `from`, this can be a previous token from a prior call to this endpoint\nor from `/messages` or `/sync`.", "example": "page3_token", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "The maximum number of results to return in a single `chunk`. The server can\nand should apply a maximum value to this parameter to avoid large responses.\n\nSimilarly, the server should apply a default value when not supplied.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Optional (default `b`) direction to return events from. If this is set to `f`, events\nwill be returned in chronological order starting at `from`. If it\nis set to `b`, events will be returned in *reverse* chronological\norder, again starting at `from`.", "in": "query", "name": "dir", "schema": { "enum": [ "b", "f" ], "type": "string" }, "x-addedInMatrixVersion": "1.4" }, { "description": "Whether to additionally include events which only relate indirectly to the\ngiven event, i.e. events related to the given event via two or more direct relationships.\n\nIf set to `false`, only events which have a direct relation with the given\nevent will be included.\n\nIf set to `true`, events which have an indirect relation with the given event\nwill be included additionally up to a certain depth level. Homeservers SHOULD traverse\nat least 3 levels of relationships. Implementations MAY perform more but MUST be careful\nto not infinitely recurse.\n\nThe default value is `false`.", "in": "query", "name": "recurse", "required": false, "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.10" } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "m.relates_to": { "event_id": "$asfDuShaf7Gafaw", "rel_type": "org.example.my_relation" } }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:matrix.org", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "next_batch": "page2_token", "prev_batch": "page1_token" } } }, "schema": { "allOf": [ { "properties": { "next_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans there are no more results to fetch and the client should stop paginating.", "type": "string" }, "prev_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans this is the start of the result set, i.e. this is the first batch/page.", "type": "string" }, "recursion_depth": { "description": "If the `recurse` parameter was supplied by the client, this response field is\nmandatory and gives the actual depth to which the server recursed. If the client\ndid not specify the `recurse` parameter, this field must be absent.", "type": "integer" } }, "type": "object" }, { "properties": { "chunk": { "description": "The child events of the requested event, ordered topologically\nmost-recent first. The events returned will match the `relType`\nsupplied in the URL.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "title": "ChildEventsChunk", "type": "array" } }, "required": [ "chunk" ], "type": "object" } ] } } }, "description": "The paginated child events which point to the parent. If no events are\npointing to the parent or the pagination yields no results, an empty `chunk`\nis returned." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Event 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" ], "title": "Error", "type": "object" } } }, "description": "The parent event was not found or the user does not have permission to read\nthis event (it might be contained in history that is not accessible to the user)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the child events for a given parent event, with a given `relType`.", "tags": [ "Event relationships" ] } }, "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": { "get": { "description": "Retrieve all of the child events for a given parent event which relate to the parent\nusing the given `relType` and have the given `eventType`.\n\nNote that when paginating the `from` token should be \"after\" the `to` token in\nterms of topological ordering, because it is only possible to paginate \"backwards\"\nthrough events, starting at `from`.\n\nFor example, passing a `from` token from page 2 of the results, and a `to` token\nfrom page 1, would return the empty set. The caller can use a `from` token from\npage 1 and a `to` token from page 2 to paginate over the same range, however.", "operationId": "getRelatingEventsWithRelTypeAndEventType", "parameters": [ { "description": "The ID of the room containing the parent event.", "example": "!636q39766251:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The ID of the parent event whose child events are to be returned.", "example": "$asfDuShaf7Gafaw", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, { "description": "The [relationship type](https://spec.matrix.org/v1.19/client-server-api/#relationship-types) to search for.", "example": "org.example.my_relation", "in": "path", "name": "relType", "required": true, "schema": { "type": "string" } }, { "description": "The event type of child events to search for.\n\nNote that in encrypted rooms this will typically always be `m.room.encrypted`\nregardless of the event type contained within the encrypted payload.", "example": "m.room.message", "in": "path", "name": "eventType", "required": true, "schema": { "type": "string" } }, { "description": "The pagination token to start returning results from. If not supplied, results\nstart at the most recent topological event known to the server.\n\nCan be a `next_batch` or `prev_batch` token from a previous call, or a returned\n`start` token from [`/messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync).", "example": "page2_token", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The pagination token to stop returning results at. If not supplied, results\ncontinue up to `limit` or until there are no more events.\n\nLike `from`, this can be a previous token from a prior call to this endpoint\nor from `/messages` or `/sync`.", "example": "page3_token", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "The maximum number of results to return in a single `chunk`. The server can\nand should apply a maximum value to this parameter to avoid large responses.\n\nSimilarly, the server should apply a default value when not supplied.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Optional (default `b`) direction to return events from. If this is set to `f`, events\nwill be returned in chronological order starting at `from`. If it\nis set to `b`, events will be returned in *reverse* chronological\norder, again starting at `from`.", "in": "query", "name": "dir", "schema": { "enum": [ "b", "f" ], "type": "string" }, "x-addedInMatrixVersion": "1.4" }, { "description": "Whether to additionally include events which only relate indirectly to the\ngiven event, i.e. events related to the given event via two or more direct relationships.\n\nIf set to `false`, only events which have a direct relation with the given\nevent will be included.\n\nIf set to `true`, events which have an indirect relation with the given event\nwill be included additionally up to a certain depth level. Homeservers SHOULD traverse\nat least 3 levels of relationships. Implementations MAY perform more but MUST be careful\nto not infinitely recurse.\n\nThe default value is `false`.", "in": "query", "name": "recurse", "required": false, "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.10" } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "m.relates_to": { "event_id": "$asfDuShaf7Gafaw", "rel_type": "org.example.my_relation" } }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:matrix.org", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "next_batch": "page2_token", "prev_batch": "page1_token" } } }, "schema": { "allOf": [ { "properties": { "next_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans there are no more results to fetch and the client should stop paginating.", "type": "string" }, "prev_batch": { "description": "An opaque string representing a pagination token. The absence of this token\nmeans this is the start of the result set, i.e. this is the first batch/page.", "type": "string" }, "recursion_depth": { "description": "If the `recurse` parameter was supplied by the client, this response field is\nmandatory and gives the actual depth to which the server recursed. If the client\ndid not specify the `recurse` parameter, this field must be absent.", "type": "integer" } }, "type": "object" }, { "properties": { "chunk": { "description": "The child events of the requested event, ordered topologically most-recent\nfirst. The events returned will match the `relType` and `eventType` supplied\nin the URL.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "title": "ChildEventsChunk", "type": "array" } }, "required": [ "chunk" ], "type": "object" } ] } } }, "description": "The paginated child events which point to the parent. If no events are\npointing to the parent or the pagination yields no results, an empty `chunk`\nis returned." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Event 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" ], "title": "Error", "type": "object" } } }, "description": "The parent event was not found or the user does not have permission to read\nthis event (it might be contained in history that is not accessible to the user)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the child events for a given parent event, with a given `relType` and `eventType`.", "tags": [ "Event relationships" ] } }, "/_matrix/client/v1/rooms/{roomId}/threads": { "get": { "description": "This API is used to paginate through the list of the thread roots in a given room. \n\nOptionally, the returned list may be filtered according to whether the requesting\nuser has participated in the thread.", "operationId": "getThreadRoots", "parameters": [ { "description": "The room ID where the thread roots are located.", "example": "!room:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "Optional (default `all`) flag to denote which thread roots are of interest to the caller.\nWhen `all`, all thread roots found in the room are returned. When `participated`, only\nthread roots for threads the user has [participated in](https://spec.matrix.org/v1.19/client-server-api/#server-side-aggregation-of-mthread-relationships)\nwill be returned.", "example": "all", "in": "query", "name": "include", "schema": { "enum": [ "all", "participated" ], "type": "string" } }, { "description": "Optional limit for the maximum number of thread roots to include per response. Must be an integer\ngreater than zero.\n\nServers should apply a default value, and impose a maximum value to avoid resource exhaustion.", "example": 20, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "A pagination token from a previous result. When not provided, the server starts paginating from\nthe most recent event visible to the user (as per history visibility rules; topologically).", "example": "next_batch_token", "in": "query", "name": "from", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } } ], "next_batch": "next_batch_token" } } }, "schema": { "properties": { "chunk": { "description": "The thread roots, ordered by the `latest_event` in each event's aggregated children. All events\nreturned include bundled [aggregations](https://spec.matrix.org/v1.19/client-server-api/#aggregations-of-child-events).\n\nIf the thread root event was sent by an [ignored user](https://spec.matrix.org/v1.19/client-server-api/#ignoring-users), the\nevent is returned redacted to the caller. This is to simulate the same behaviour of a client doing\naggregation locally on the thread.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "next_batch": { "description": "A token to supply to `from` to keep paginating the responses. Not present when there are\nno further results.", "type": "string" } }, "required": [ "chunk" ], "type": "object" } } }, "description": "A portion of the available thread roots in the room, based on the filter criteria." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "Unknown pagination 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" ], "title": "Error", "type": "object" } } }, "description": "The request was invalid in some way. A meaningful `errcode`\nand description error text will be returned. Example reasons for rejection are:\n\n- The `from` token is unknown to the server." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "You are not allowed to view 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" ], "title": "Error", "type": "object" } } }, "description": "The user cannot view or peek on the room. A meaningful `errcode`\nand description error text will be returned. Example reasons for rejection are:\n\n- The room is not set up for peeking.\n- The user has been banned from the room.\n- The room does not exist." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Fetches a list of the threads in a room.", "tags": [ "Threads" ], "x-addedInMatrixVersion": "1.4" } }, "/_matrix/client/v1/rooms/{roomId}/timestamp_to_event": { "get": { "description": "Get the ID of the event closest to the given timestamp, in the\ndirection specified by the `dir` parameter.\n\nIf the server does not have all of the room history and does not have\nan event suitably close to the requested timestamp, it can use the\ncorresponding [federation endpoint](https://spec.matrix.org/v1.19/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)\nto ask other servers for a suitable event.\n\nAfter calling this endpoint, clients can call\n[`/rooms/{roomId}/context/{eventId}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidcontexteventid)\nto obtain a pagination token to retrieve the events around the returned event.\n\nThe event returned by this endpoint could be an event that the client\ncannot render, and so may need to paginate in order to locate an event\nthat it can display, which may end up being outside of the client's\nsuitable range. Clients can employ different strategies to display\nsomething reasonable to the user. For example, the client could try\npaginating in one direction for a while, while looking at the\ntimestamps of the events that it is paginating through, and if it\nexceeds a certain difference from the target timestamp, it can try\npaginating in the opposite direction. The client could also simply\npaginate in one direction and inform the user that the closest event\nfound in that direction is outside of the expected range.", "operationId": "getEventByTimestamp", "parameters": [ { "description": "The ID of the room to search", "example": "!636q39766251:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The timestamp to search from, as given in milliseconds\nsince the Unix epoch.", "example": 1432684800000, "in": "query", "name": "ts", "required": true, "schema": { "type": "integer" } }, { "description": "The direction in which to search. `f` for forwards, `b` for backwards.", "example": "f", "in": "query", "name": "dir", "required": true, "schema": { "enum": [ "f", "b" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653 } } }, "schema": { "properties": { "event_id": { "description": "The ID of the event found", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "The event's timestamp, in milliseconds since the Unix epoch.\nThis makes it easy to do a quick comparison to see if the\n`event_id` fetched is too far out of range to be useful for your\nuse case.", "type": "integer" } }, "required": [ "event_id", "origin_server_ts" ], "type": "object" } } }, "description": "An event was found matching the search parameters." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unable to find event from 1432684800000 in forward direction" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "No event was found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the closest event ID to the given timestamp", "tags": [ "Room participation" ], "x-addedInMatrixVersion": "1.6" } }, "/_matrix/client/v3/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": { "content": { "application/json": { "examples": { "response": { "value": { "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" } } }, "description": "The lookup was successful." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets a list of a user's third-party identifiers.", "tags": [ "Account management" ] }, "post": { "deprecated": true, "description": "Adds contact information to the user's account.\n\nThis endpoint is deprecated in favour of the more specific `/3pid/add`\nand `/3pid/bind` endpoints.\n\n**Note:**\nPreviously this endpoint supported a `bind` parameter. This parameter\nhas been removed, making this endpoint behave as though it was `false`.\nThis results in this endpoint being an equivalent to `/3pid/bind` rather\nthan dual-purpose.\n\nThis endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation).\nClients SHOULD check the value of the [`m.3pid_changes` capability](https://spec.matrix.org/v1.19/client-server-api/#m3pid_changes-capability)\nto determine if this endpoint is available.", "operationId": "post3PIDs", "requestBody": { "content": { "application/json": { "schema": { "example": { "three_pid_creds": { "client_secret": "d0nt-T3ll", "id_access_token": "abc123_OpaqueString", "id_server": "matrix.org", "sid": "abc123987" } }, "properties": { "three_pid_creds": { "description": "The third-party credentials to associate with the account.", "properties": { "client_secret": { "description": "The client secret used in the session with the identity server.", "type": "string" }, "id_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 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" ], "title": "ThreePidCredentials", "type": "object" } }, "required": [ "three_pid_creds" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "submit_url": "https://example.org/path/to/submitToken" } } }, "schema": { "properties": { "submit_url": { "description": "An optional field containing a URL where the client must\nsubmit the validation token to, with identical parameters\nto the Identity Service API's `POST\n/validate/email/submitToken` endpoint (without the requirement\nfor an access token). The homeserver must send this token to the\nuser (if applicable), who should then be prompted to provide it\nto the client.\n\nIf this field is not present, the client can assume that\nverification will happen without the client's involvement\nprovided the homeserver advertises this specification version\nin the `/versions` response (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string" } }, "type": "object" } } }, "description": "The addition was successful." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_AUTH_FAILED", "error": "The third-party credentials could not be verified by the identity server." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The credentials could not be verified with the identity server." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Adds contact information to the user's account.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/3pid/add": { "post": { "description": "This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api).\n\nAdds contact information to the user's account. Homeservers should use 3PIDs added\nthrough this endpoint for password resets instead of relying on the identity server.\n\nHomeservers should prevent the caller from adding a 3PID to their account if it has\nalready been added to another user's account on the homeserver.\n\nThis endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation).\nClients SHOULD check the value of the [`m.3pid_changes` capability](https://spec.matrix.org/v1.19/client-server-api/#m3pid_changes-capability)\nto determine if this endpoint is available.\n\n**WARNING:** \nSince this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained\nvia the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\n", "operationId": "add3PID", "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the\nuser-interactive authentication API." }, "client_secret": { "description": "The client secret used in the session with the homeserver.", "example": "d0nt-T3ll", "type": "string" }, "sid": { "description": "The session identifier given by the homeserver.", "example": "abc123987", "type": "string" } }, "required": [ "client_secret", "sid" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The addition was successful." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Adds contact information to the user's account.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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", "requestBody": { "content": { "application/json": { "schema": { "example": { "client_secret": "d0nt-T3ll", "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The addition was successful." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Binds a 3PID to the user's account through an Identity Service.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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.\n\nThis endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation).\nClients SHOULD check the value of the [`m.3pid_changes` capability](https://spec.matrix.org/v1.19/client-server-api/#m3pid_changes-capability)\nto determine if this endpoint is available.", "operationId": "delete3pidFromAccount", "requestBody": { "content": { "application/json": { "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "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\nidentity 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" } } }, "description": "The homeserver has disassociated the third-party identifier from the\nuser." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Deletes a third-party identifier from the user's account", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/3pid/email/requestToken": { "post": { "description": "The homeserver must check that the given email address is **not**\nalready associated with an account on this homeserver. This API should\nbe used to request validation tokens when adding an email address to an\naccount. This API's parameters and response are identical to that of\nthe [`/register/email/requestToken`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3registeremailrequesttoken)\nendpoint. The homeserver should validate\nthe email itself, either by sending a validation email itself or by using\na service it has control over.", "operationId": "requestTokenTo3PIDEmail", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "email": { "description": "The email address to validate.", "example": "alice@example.org", "format": "email", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "send_attempt": { "description": "The server will only send an email if the `send_attempt`\nis a number greater than the most recent one which it has seen,\nscoped to that `email` + `client_secret` pair. This is to\navoid repeatedly sending the same email in the case of request\nretries between the POSTing user and the identity server.\nThe client should increment this value if they desire a new\nemail (e.g. a reminder) to be sent. If they do not, the server\nshould respond with success but not resend the email.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "email", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An email was sent to the given address. Note that this may be an\nemail containing the validation token or it may be informing the\nuser of an error." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_IN_USE", "error": "Third-party identifier already in use" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The third-party identifier is already in use on the homeserver, or\nthe request was invalid. Error codes that can be returned are:\n * `M_THREEPID_IN_USE`: The email supplied cannot be bound because is is already\n associated with a different Matrix ID.\n * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server\n provided in the request.\n * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding email addresses.\n * `M_INVALID_PARAM`: The email address given was not valid." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not allow the third-party identifier as a\ncontact option." } }, "summary": "Begins the validation process for an email address for association with the user's account.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/3pid/msisdn/requestToken": { "post": { "description": "The homeserver must check that the given phone number is **not**\nalready associated with an account on this homeserver. This API should\nbe used to request validation tokens when adding a phone number to an\naccount. This API's parameters and response are identical to that of\nthe [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)\nendpoint. The homeserver should validate\nthe phone number itself, either by sending a validation message itself or by using\na service it has control over.", "operationId": "requestTokenTo3PIDMSISDN", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "country": { "description": "The two-letter uppercase ISO-3166-1 alpha-2 country code that the\nnumber in `phone_number` should be parsed as if it were dialled from.", "example": "GB", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "phone_number": { "description": "The phone number to validate.", "example": "07700900001", "type": "string" }, "send_attempt": { "description": "The server will only send an SMS if the `send_attempt` is a\nnumber greater than the most recent one which it has seen,\nscoped to that `country` + `phone_number` + `client_secret`\ntriple. This is to avoid repeatedly sending the same SMS in\nthe case of request retries between the POSTing user and the\nidentity server. The client should increment this value if\nthey desire a new SMS (e.g. a reminder) to be sent.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "country", "phone_number", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An SMS message was sent to the given phone number." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_IN_USE", "error": "Third-party identifier already in use" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The third-party identifier is already in use on the homeserver, or\nthe request was invalid. Error codes that can be returned are:\n * `M_THREEPID_IN_USE`: The phone number supplied cannot be bound because is is already\n associated with a different Matrix ID.\n * `M_SERVER_NOT_TRUSTED`: The server does not trust/support the identity server\n * `M_THREEPID_MEDIUM_NOT_SUPPORTED`: The homeserver does not support adding phone numbers.\n * `M_INVALID_PARAM`: The phone number given was not valid." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not allow the third-party identifier as a\ncontact option." } }, "summary": "Begins the validation process for a phone number for association with the user's account.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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", "requestBody": { "content": { "application/json": { "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "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" } } }, "description": "The identity server has disassociated the third-party identifier from the\nuser." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Removes a user's third-party identifier from an identity server.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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](https://spec.matrix.org/v1.19/client-server-api/#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.\n\n**WARNING:** \n**[Added in `v1.18`]** [OAuth 2.0 aware clients](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-aware-clients)\nMUST NOT use this endpoint when the server supports the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\nInstead they MUST refer the user to the [account management URL](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-account-management),\nif available, and MAY use the `action=org.matrix.account_deactivate`\nparameter.\n", "operationId": "deactivateAccount", "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the user-interactive authentication API." }, "erase": { "description": "Whether the user would like their content to be erased as\nmuch as possible from the server.\n\nErasure means that any users (or servers) which join the\nroom after the erasure request are served redacted copies of\nthe events sent by this account. Users which had visibility\non those events prior to the erasure are still able to see\nunredacted copies. No redactions are sent and the erasure\nrequest is not shared over federation, so other servers\nmight still serve unredacted copies.\n\nThe server should additionally erase any non-event data\nassociated with the user, such as [account data](https://spec.matrix.org/v1.19/client-server-api/#client-config)\nand [contact 3PIDs](https://spec.matrix.org/v1.19/client-server-api/#adding-account-administrative-contact-information).\n\nDefaults to `false` if not present.", "type": "boolean", "x-addedInMatrixVersion": "1.10" }, "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "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" } } }, "description": "The account has been deactivated." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ {}, { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Deactivate a user's account.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/password": { "post": { "description": "Changes the password for an account on this homeserver.\n\nThis API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#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.\n\nThis endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation).\nClients SHOULD check the value of the [`m.change_password` capability](https://spec.matrix.org/v1.19/client-server-api/#mchange_password-capability)\nto determine if this endpoint is available.", "operationId": "changePassword", "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the user-interactive authentication API." }, "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](https://spec.matrix.org/v1.19/client-server-api/#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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The password has been changed." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ {}, { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Changes a user's password.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/password/email/requestToken": { "post": { "description": "The homeserver must check that the given email address **is\nassociated** with an account on this homeserver. This API should be\nused to request validation tokens when authenticating for the\n`/account/password` endpoint.\n\nThis API's parameters and response are identical to that of the\n[`/register/email/requestToken`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3registeremailrequesttoken)\nendpoint, except that\n`M_THREEPID_NOT_FOUND` may be returned if no account matching the\ngiven email address could be found. The server may instead send an\nemail to the given address prompting the user to create an account.\n`M_THREEPID_IN_USE` may not be returned.\n\nThe homeserver should validate the email itself, either by sending a\nvalidation email itself or by using a service it has control over.", "operationId": "requestTokenToResetPasswordEmail", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "email": { "description": "The email address to validate.", "example": "alice@example.org", "format": "email", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "send_attempt": { "description": "The server will only send an email if the `send_attempt`\nis a number greater than the most recent one which it has seen,\nscoped to that `email` + `client_secret` pair. This is to\navoid repeatedly sending the same email in the case of request\nretries between the POSTing user and the identity server.\nThe client should increment this value if they desire a new\nemail (e.g. a reminder) to be sent. If they do not, the server\nshould respond with success but not resend the email.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "email", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An email was sent to the given address." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_NOT_FOUND", "error": "Email 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" ], "title": "Error", "type": "object" } } }, "description": "The referenced third-party identifier is not recognised by the\nhomeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`\ncan be returned if the server does not trust/support the identity server\nprovided in the request." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not allow the third-party identifier as a\ncontact option." } }, "summary": "Requests a validation token be sent to the given email address for the purpose of resetting a user's password", "tags": [ "Account management" ] } }, "/_matrix/client/v3/account/password/msisdn/requestToken": { "post": { "description": "The homeserver must check that the given phone number **is\nassociated** with an account on this homeserver. This API should be\nused to request validation tokens when authenticating for the\n`/account/password` endpoint.\n\nThis API's parameters and response are identical to that of the\n[`/register/msisdn/requestToken`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3registermsisdnrequesttoken)\nendpoint, except that\n`M_THREEPID_NOT_FOUND` may be returned if no account matching the\ngiven phone number could be found. The server may instead send the SMS\nto the given phone number prompting the user to create an account.\n`M_THREEPID_IN_USE` may not be returned.\n\nThe homeserver should validate the phone number itself, either by sending a\nvalidation message itself or by using a service it has control over.", "operationId": "requestTokenToResetPasswordMSISDN", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "country": { "description": "The two-letter uppercase ISO-3166-1 alpha-2 country code that the\nnumber in `phone_number` should be parsed as if it were dialled from.", "example": "GB", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "phone_number": { "description": "The phone number to validate.", "example": "07700900001", "type": "string" }, "send_attempt": { "description": "The server will only send an SMS if the `send_attempt` is a\nnumber greater than the most recent one which it has seen,\nscoped to that `country` + `phone_number` + `client_secret`\ntriple. This is to avoid repeatedly sending the same SMS in\nthe case of request retries between the POSTing user and the\nidentity server. The client should increment this value if\nthey desire a new SMS (e.g. a reminder) to be sent.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "country", "phone_number", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An SMS message was sent to the given phone number." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_NOT_FOUND", "error": "Phone number 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" ], "title": "Error", "type": "object" } } }, "description": "The referenced third-party identifier is not recognised by the\nhomeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED`\ncan be returned if the server does not trust/support the identity server\nprovided in the request." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not allow the third-party identifier as a\ncontact option." } }, "summary": "Requests a validation token be sent to the given phone number for the purpose of resetting a user's password.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "device_id": "ABC1234", "user_id": "@joe:example.org" } } }, "schema": { "properties": { "device_id": { "description": "Device ID associated with the access token. If no device\nis associated with the access token (such as in the case\nof application services) then this field can be omitted.\nOtherwise this is required.", "type": "string", "x-addedInMatrixVersion": "1.1" }, "is_guest": { "description": "When `true`, the user is a [Guest User](https://spec.matrix.org/v1.19/client-server-api/#guest-access).\nWhen not present or `false`, the user is presumed to be a \nnon-guest user.", "type": "boolean", "x-addedInMatrixVersion": "1.2" }, "user_id": { "description": "The user ID that owns the access token.", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "description": "The token belongs to a known user." }, "401": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The token is not recognised" }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The appservice cannot masquerade as the user or has not registered them." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets information about the owner of an access token.", "tags": [ "Session management" ] } }, "/_matrix/client/v3/admin/whois/{userId}": { "get": { "description": "Gets information about a particular user.\n\nThis API may be restricted to only be called by the user being looked\nup, or by a server admin. Server-local administrator privileges are not\nspecified in this document.", "operationId": "getWhoIs", "parameters": [ { "description": "The user to look up.", "example": "@peter:rabbit.rocks", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "devices": { "teapot": { "sessions": [ { "connections": [ { "ip": "127.0.0.1", "last_seen": 1411996332123, "user_agent": "curl/7.31.0-DEV" }, { "ip": "10.0.0.2", "last_seen": 1411996332123, "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/37.0.2062.120 Safari/537.36" } ] } ] } }, "user_id": "@peter:rabbit.rocks" } } }, "schema": { "properties": { "devices": { "additionalProperties": { "properties": { "sessions": { "description": "A user's sessions (i.e. what they did with an access token from one login).", "items": { "properties": { "connections": { "description": "Information particular connections in the session.", "items": { "properties": { "ip": { "description": "Most recently seen IP address of the session.", "type": "string" }, "last_seen": { "description": "Unix timestamp that the session was last active.", "format": "int64", "type": "integer" }, "user_agent": { "description": "User agent string last seen in the session.", "type": "string" } }, "title": "ConnectionInfo", "type": "object" }, "type": "array" } }, "title": "SessionInfo", "type": "object" }, "type": "array" } }, "title": "DeviceInfo", "type": "object" }, "description": "Each key is an identifier for one of the user's devices.", "type": "object" }, "user_id": { "description": "The Matrix user ID of the user.", "type": "string" } }, "type": "object" } } }, "description": "The lookup was successful." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets information about a particular user.", "tags": [ "Server administration" ] } }, "/_matrix/client/v3/capabilities": { "get": { "description": "Gets information about the server's supported feature set\nand other relevant capabilities.", "operationId": "getCapabilities", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "description": "Application-dependent keys using the\n[Common Namespaced Identifier Grammar](https://spec.matrix.org/v1.19/appendices/#common-namespaced-identifier-grammar)." }, "description": "The custom capabilities the server supports, using the\nJava package naming convention.", "properties": { "m.3pid_changes": { "description": "Capability to indicate if the user can change 3PID associations on their account.", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object" }, "m.account_moderation": { "description": "Capability to indicate if the user can perform account moderation actions\nvia [server administration](https://spec.matrix.org/v1.19/client-server-api/#server-administration)\nendpoints.\n\nThis property should be omitted altogether if `suspend` and `lock` would\nbe `false`.", "properties": { "lock": { "description": "`true` if the user can lock a user via [`PUT /admin/lock/{userId}`](https://spec.matrix.org/v1.19/client-server-api/#put_matrixclientv1adminlockuserid),\n`false` otherwise.\n\nDefaults to `false`.", "example": true, "type": "boolean" }, "suspend": { "description": "`true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](https://spec.matrix.org/v1.19/client-server-api/#put_matrixclientv1adminsuspenduserid),\n`false` otherwise.\n\nDefaults to `false`.", "example": true, "type": "boolean" } }, "title": "AccountModerationCapability", "type": "object", "x-addedInMatrixVersion": "1.18" }, "m.change_password": { "description": "Capability to indicate if the user can change their password.", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object" }, "m.forget_forced_upon_leave": { "description": "Capability to indicate if the server automatically forgets rooms once the user\nleaves.", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object", "x-addedInMatrixVersion": "1.18" }, "m.get_login_token": { "description": "Capability to indicate if the user can generate tokens to log further clients into their account.", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object" }, "m.profile_fields": { "description": "Capability to indicate if the user can set or modify extended profile fields via [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](https://spec.matrix.org/v1.19/client-server-api/#put_matrixclientv3profileuseridkeyname). If absent, clients SHOULD assume custom profile fields are supported, provided the homeserver advertises a specification version that includes `m.profile_fields` in the [`/versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions) response.", "properties": { "allowed": { "description": "If present, a list of profile fields that clients are allowed to create, modify or delete,\nprovided `enabled` is `true`; no other profile fields may be changed.\n\nIf absent, clients may set all profile fields except those forbidden by the `disallowed`\nlist, where present.\n", "example": [ "m.example_field", "org.example.job_title" ], "items": { "type": "string" }, "type": "array" }, "disallowed": { "description": "This property has no meaning if `allowed` is also specified.\n\nOtherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.\nProvided `enabled` is `true`, clients MAY assume that they can set any profile field which is not\nincluded in this list.\n", "example": [ "org.example.managed_field" ], "items": { "type": "string" }, "type": "array" }, "enabled": { "description": "`true` if the user can create, update or delete any profile fields, `false` otherwise.", "example": true, "type": "boolean" } }, "required": [ "enabled" ], "title": "ProfileFieldsCapability", "type": "object", "x-addedInMatrixVersion": "1.16" }, "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.", "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" }, "m.set_avatar_url": { "deprecated": true, "description": "**Deprecated:** Capability to indicate if the user can change their avatar.\nRefer to `m.profile_fields` for extended profile management.\n\nFor backwards compatibility, servers that directly or indirectly include the\n`avatar_url` profile field in the `m.profile_fields` capability MUST also\nset this capability accordingly.\n", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object" }, "m.set_displayname": { "deprecated": true, "description": "**Deprecated:** Capability to indicate if the user can change their display name.\nRefer to `m.profile_fields` for extended profile management.\n\nFor backwards compatibility, servers that directly or indirectly include the\n`displayname` profile field in the `m.profile_fields` capability MUST also\nset this capability accordingly.\n", "properties": { "enabled": { "description": "True if the user can perform the action, false otherwise.", "example": false, "type": "boolean" } }, "required": [ "enabled" ], "title": "BooleanCapability", "type": "object" } }, "title": "Capabilities", "type": "object" } }, "required": [ "capabilities" ], "type": "object" } } }, "description": "The capabilities of the server." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets information about the server's capabilities.", "tags": [ "Capabilities" ] } }, "/_matrix/client/v3/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. Overridden by the\n `power_level_content_override` parameter.\n\n In [room versions](https://spec.matrix.org/v1.19/rooms) 1 through 11, the room creator (and not\n other members) will be given permission to send state events.\n\n In room versions 12 and later, the room creator is given infinite\n power level and cannot be specified in the `users` field of\n `m.room.power_levels`, so is not listed explicitly.\n\n **Note**: For `trusted_private_chat`, the users specified in the\n `invite` parameter SHOULD also be appended to `additional_creators`\n by the server, per the `creation_content` parameter.\n\n If the room's version is 12 or higher, the power level for sending\n `m.room.tombstone` events MUST explicitly be higher than `state_default`.\n For example, set to 150 instead of 100.\n\n4. An `m.room.canonical_alias` event if `room_alias_name` is given.\n\n5. 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\n6. Events listed in `initial_state`, in the order that they are\n listed.\n\n7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic`\n state events).\n\n8. 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| 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\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` or implied by behaviour of `creation_content`.", "operationId": "createRoom", "requestBody": { "content": { "application/json": { "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`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate) event.\n\nThe server will overwrite the following\nkeys: `creator`, `room_version`. Future versions of the specification\nmay allow the server to overwrite other keys.\n\nWhen using the `trusted_private_chat` preset, the server SHOULD combine\n`additional_creators` specified here and the `invite` array into the\neventual `m.room.create` event's `additional_creators`, deduplicating\nbetween the two parameters.", "title": "CreationContent", "type": "object", "x-changedInMatrixVersion": { "1.16": "Added server behaviour for how to handle `trusted_private_chat` and invited users." } }, "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\noverridden 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": { "format": "mx-user-id", "pattern": "^@", "type": "string" }, "type": "array" }, "invite_3pid": { "description": "A list of objects representing third-party IDs to invite into\nthe room.", "items": { "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`\n(see [the list of recognised values](https://spec.matrix.org/v1.19/appendices/#3pid-types)).", "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](https://spec.matrix.org/v1.19/client-server-api/#direct-messaging) for more information.", "type": "boolean" }, "name": { "description": "If this is included, an [`m.room.name`](https://spec.matrix.org/v1.19/client-server-api/#mroomname) event\nwill be sent into the room to indicate the name for the room.\nThis overwrites any [`m.room.name`](https://spec.matrix.org/v1.19/client-server-api/#mroomname)\nevent in `initial_state`.", "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\n[`m.room.power_levels`](https://spec.matrix.org/v1.19/client-server-api/#mroompower_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 visibility 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 and an `m.room.canonical_alias` event will be sent\ninto the 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`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic)\nevent with a `text/plain` mimetype will be sent into the room\nto indicate the topic for the room. This overwrites any\n[`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic) event in `initial_state`.", "type": "string" }, "visibility": { "description": "The room's visibility in the server's\n[published room directory](https://spec.matrix.org/v1.19/client-server-api#published-room-directory).\nDefaults to `private`.", "enum": [ "public", "private" ], "type": "string" } }, "type": "object" } } }, "description": "The desired room configuration.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "room_id": "!sefiuhWgwghwWgh:example.com" } } }, "schema": { "description": "Information about the newly created room.", "properties": { "room_id": { "description": "The created room's ID.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } } }, "description": "Information about the newly created room." }, "400": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "description": "The 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." }, "403": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "description": "Creating the room is not allowed.\n\n**[Added in `v1.18`]** The `M_INVITE_BLOCKED` error code is used to\nindicate that one of the homeservers of the invited users rejected\nthe invite due to [invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Create a new room", "tags": [ "Room creation" ], "x-changedInMatrixVersion": { "1.16": "Added server behaviour for how the initial power levels change depending on room version." } } }, "/_matrix/client/v3/delete_devices": { "post": { "description": "This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api),\nexcept when used by an application service.\n\nDeletes the given devices, and invalidates any access token associated with them.\n\n**WARNING:** \nWhen this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained\nvia the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\n\n\n**WARNING:** \n**[Added in `v1.18`]** [OAuth 2.0 aware clients](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-aware-clients)\nMUST NOT use this endpoint when the server supports the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\nInstead they MUST refer the user to the [account management URL](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-account-management),\nif available.\n", "operationId": "deleteDevices", "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the\nuser-interactive authentication API." }, "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The devices were successfully removed, or had been removed\npreviously." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Bulk deletion of devices", "tags": [ "Device management" ], "x-changedInMatrixVersion": { "1.17": "This endpoint no longer requires User-Interactive Authentication when used by an\napplication service." } } }, "/_matrix/client/v3/devices": { "get": { "description": "Gets information about all devices for the current user.", "operationId": "getDevices", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "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": "array" } }, "type": "object" } } }, "description": "Device information" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "List registered devices for the current user", "tags": [ "Device management" ] } }, "/_matrix/client/v3/devices/{deviceId}": { "delete": { "description": "This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api),\nexcept when used by an application service.\n\nDeletes the given device, and invalidates any access token associated with it.\n\n**WARNING:** \nWhen this endpoint requires User-Interactive Authentication, it cannot be used when the access token was obtained\nvia the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\n\n\n**WARNING:** \n**[Added in `v1.18`]** [OAuth 2.0 aware clients](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-aware-clients)\nMUST NOT use this endpoint when the server supports the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\nInstead they MUST refer the user to the [account management URL](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-account-management),\nif available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters.\n", "operationId": "deleteDevice", "parameters": [ { "description": "The device to delete.", "example": "QBUAZIFURK", "in": "path", "name": "deviceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the\nuser-interactive authentication API." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The device was successfully removed, or had been removed\npreviously." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete a device", "tags": [ "Device management" ], "x-changedInMatrixVersion": { "1.17": "This endpoint no longer requires User-Interactive Authentication when used by an\napplication service." } }, "get": { "description": "Gets information on a single device, by device id.", "operationId": "getDevice", "parameters": [ { "description": "The device to retrieve.", "example": "QBUAZIFURK", "in": "path", "name": "deviceId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "device_id": "QBUAZIFURK", "display_name": "android", "last_seen_ip": "1.2.3.4", "last_seen_ts": 1474491775024 } } }, "schema": { "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" } } }, "description": "Device information" }, "404": { "description": "The current user has no device with the given ID." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get a single device", "tags": [ "Device management" ] }, "put": { "description": "Updates the metadata on the given device, or creates a new device.\n\nThe ability to create new devices is only available to application\nservices: regular clients may only update existing devices.\n\nWhen a new device was created, the homeserver MUST return a 201 HTTP\nstatus code. It MUST return a 200 HTTP status code if a device was\nupdated.\n\nThis endpoint is rate-limited for device creation. Servers MAY use login\nrate limits.", "operationId": "updateDevice", "parameters": [ { "description": "The device to update.", "example": "QBUAZIFURK", "in": "path", "name": "deviceId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "display_name": "My other phone" }, "properties": { "display_name": { "description": "The new display name for this device. If not given, the\ndisplay name is unchanged.", "type": "string" } }, "type": "object" } } }, "description": "New information for the device.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The device was successfully updated." }, "201": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The device was successfully created by the application service." }, "404": { "description": "The current user has no device with the given ID." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Create or update a device", "tags": [ "Device management" ], "x-changedInMatrixVersion": { "1.17": "The ability to create new devices was added." } } }, "/_matrix/client/v3/directory/list/appservice/{networkId}/{roomId}": { "put": { "description": "Updates the visibility of a given room in the application service's\npublished room directory.\n\nThis API is similar to the\n[visibility API](https://spec.matrix.org/v1.19/client-server-api#put_matrixclientv3directorylistroomroomid)\nused by clients to update the homeserver's more general published 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": "updateAppserviceRoomDirectoryVisibility", "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.", "example": "irc", "in": "path", "name": "networkId", "required": true, "schema": { "type": "string" } }, { "description": "The room ID to add to the directory.", "example": "!somewhere:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The room's directory visibility has been updated." } }, "security": [ { "appserviceAccessTokenQuery": [] }, { "appserviceAccessTokenBearer": [] } ], "summary": "Updates a room's visibility in the application service's published room\ndirectory.", "tags": [ "Application service room directory management" ] } }, "/_matrix/client/v3/directory/list/room/{roomId}": { "get": { "description": "Gets the visibility of a given room in the server's\npublished room directory.", "operationId": "getRoomVisibilityOnDirectory", "parameters": [ { "description": "The room ID.", "example": "!curbf:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "visibility": "public" } } }, "schema": { "properties": { "visibility": { "description": "The visibility of the room in the directory.", "enum": [ "private", "public" ], "type": "string" } }, "type": "object" } } }, "description": "The visibility of the room in the directory." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Room 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" ], "title": "Error", "type": "object" } } }, "description": "The room is not known to the server." } }, "summary": "Gets the visibility of a room in the directory", "tags": [ "Room discovery" ] }, "put": { "description": "Sets the visibility of a given room in the server's published room directory.\n\nServers MAY implement additional access control checks, for instance,\nto ensure that a room's visibility can only be changed by the room creator\nor a server administrator.", "operationId": "setRoomVisibilityOnDirectory", "parameters": [ { "description": "The room ID.", "example": "!curbf:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "visibility": "public" }, "properties": { "visibility": { "description": "The new visibility setting for the room.\nDefaults to `public`.", "enum": [ "private", "public" ], "type": "string" } }, "type": "object" } } }, "description": "The new visibility for the room in the published room directory.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The visibility was updated, or no change was needed." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Room 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" ], "title": "Error", "type": "object" } } }, "description": "The room is not known to the server." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Sets the visibility of a room in the directory", "tags": [ "Room discovery" ] } }, "/_matrix/client/v3/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:**\nServers may choose to update the `alt_aliases` for the `m.room.canonical_alias`\nstate event in the room when an alias is removed. Servers which choose to update the\ncanonical alias event are recommended to, in addition to their other relevant permission\nchecks, delete the alias and return a successful response even if the user does not\nhave permission to update the `m.room.canonical_alias` event.", "operationId": "deleteRoomAlias", "parameters": [ { "description": "The room alias to remove. Its format is defined\n[in the appendices](https://spec.matrix.org/v1.19/appendices/#room-aliases).\n", "example": "#monkeys:matrix.org", "in": "path", "name": "roomAlias", "required": true, "schema": { "format": "mx-room-alias", "pattern": "^#", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The mapping was deleted." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "There is no mapped room ID for this room alias." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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. Its format is defined\n[in the appendices](https://spec.matrix.org/v1.19/appendices/#room-aliases).\n", "example": "#monkeys:matrix.org", "in": "path", "name": "roomAlias", "required": true, "schema": { "format": "mx-room-alias", "pattern": "^#", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "room_id": "!abnjk1jdasj98:capuchins.com", "servers": [ "capuchins.com", "matrix.org", "another.com" ] } } }, "schema": { "properties": { "room_id": { "description": "The room ID for this room alias.", "format": "mx-room-id", "pattern": "^!", "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.", "format": "mx-server-name", "type": "string" }, "type": "array" } }, "type": "object" } } }, "description": "The room ID and other information for this alias." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "Room alias invalid" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The given `roomAlias` is not a valid room alias." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "There is no mapped room ID for this room alias." } }, "summary": "Get the room ID corresponding to this room alias.", "tags": [ "Room directory" ] }, "put": { "operationId": "setRoomAlias", "parameters": [ { "description": "The room alias to set. Its format is defined\n[in the appendices](https://spec.matrix.org/v1.19/appendices/#room-aliases).\n", "example": "#monkeys:matrix.org", "in": "path", "name": "roomAlias", "required": true, "schema": { "format": "mx-room-alias", "pattern": "^#", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "room_id": "!abnjk1jdasj98:capuchins.com" }, "properties": { "room_id": { "description": "The room ID to set.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } } }, "description": "Information about this room alias.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The mapping was created." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "Room alias invalid" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The given `roomAlias` is not a valid room alias." }, "409": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "A room alias with that name already exists." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Create a new mapping from room alias to room ID.", "tags": [ "Room directory" ] } }, "/_matrix/client/v3/events": { "get": { "deprecated": true, "description": "This will listen for new events and return them to the caller. This will\nblock until an event is received, or until the `timeout` is reached.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync)\nendpoint with a `since` parameter. See\nthe [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).", "operationId": "getEvents", "parameters": [ { "description": "The token to stream from. This token is either from a previous\nrequest to this API or from the initial sync API.", "example": "s3456_9_0", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The maximum time in milliseconds to wait for an event.", "example": 35000, "in": "query", "name": "timeout", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } } ], "end": "s3457_9_0", "start": "s3456_9_0" } } }, "schema": { "properties": { "chunk": { "description": "An array of events.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "end": { "description": "A token which correlates to the end of `chunk`. This\ntoken should be used in the next request to `/events`.", "type": "string" }, "start": { "description": "A token which correlates to the start of `chunk`. This\nis usually the same token supplied to `from=`.", "type": "string" } }, "type": "object" } } }, "description": "The events received, which may be none." }, "400": { "description": "Bad pagination `from` parameter." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Listen on the event stream.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/events ": { "get": { "description": "This will listen for new events related to a particular room and return\nthem to the caller. This will block until an event is received, or until\nthe `timeout` is reached.\n\nThis API is the same as the normal `/events` endpoint, but can be\ncalled by users who have not joined the room.\n\nNote that the normal `/events` endpoint has been deprecated. This\nAPI will also be deprecated at some point, but its replacement is not\nyet known.", "operationId": "peekEvents", "parameters": [ { "description": "The token to stream from. This token is either from a previous\nrequest to this API or from the initial sync API.", "example": "s3456_9_0", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "The maximum time in milliseconds to wait for an event.", "example": 35000, "in": "query", "name": "timeout", "required": false, "schema": { "type": "integer" } }, { "description": "The room ID for which events should be returned.", "example": "!somewhere:over.the.rainbow", "in": "query", "name": "room_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "msgtype": "m.text" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!somewhere:over.the.rainbow", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "end": "s3457_9_0", "start": "s3456_9_0" } } }, "schema": { "properties": { "chunk": { "description": "An array of events.", "items": { "allOf": [ { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } ], "title": "Event", "type": "object" }, "type": "array" }, "end": { "description": "A token which correlates to the last value in `chunk`. This\ntoken should be used in the next request to `/events`.", "type": "string" }, "start": { "description": "A token which correlates to the first value in `chunk`. This\nis usually the same token supplied to `from=`.", "type": "string" } }, "type": "object" } } }, "description": "The events received, which may be none." }, "400": { "description": "Bad pagination `from` parameter." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Listen on the event stream of a particular room.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/events/{eventId}": { "get": { "deprecated": true, "description": "Get a single event based on `event_id`. You must have permission to\nretrieve this event e.g. by being a member in the room for this event.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the\n[/rooms/{roomId}/event/{eventId}](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomideventeventid) API\nor the [/rooms/{roomId}/context/{eventId}](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API.", "operationId": "getOneEvent", "parameters": [ { "description": "The event ID to get.", "example": "$asfDuShaf7Gafaw:matrix.org", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } } } }, "schema": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } } }, "description": "The full event." }, "404": { "description": "The event was not found or you do not have permission to read this event." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get a single event by event ID.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/initialSync": { "get": { "deprecated": true, "description": "This returns the full state for this user, with an optional limit on the\nnumber of messages per room to return.\n\nThis endpoint was deprecated in r0 of this specification. Clients\nshould instead call the [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync)\nendpoint with no `since` parameter. See\nthe [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).", "operationId": "initialSync", "parameters": [ { "description": "The maximum number of messages to return for each room.", "example": 2, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Whether to include rooms that the user has left. If `false` then\nonly rooms that the user has been invited to or has joined are\nincluded. If set to `true` then rooms that the user has left are\nincluded as well. By default this is `false`.", "example": true, "in": "query", "name": "archived", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "account_data": [ { "content": { "custom_config_key": "custom_config_value" }, "type": "org.example.custom.config" } ], "end": "s3456_9_0", "presence": [ { "content": { "avatar_url": "mxc://localhost/wefuiwegh8742w", "currently_active": false, "last_active_ago": 2478593, "presence": "online", "status_msg": "Making cupcakes" }, "sender": "@example:localhost", "type": "m.presence" } ], "rooms": [ { "account_data": [ { "content": { "tags": { "work": { "order": 1 } } }, "type": "m.tag" }, { "content": { "custom_config_key": "custom_config_value" }, "type": "org.example.custom.room.config" } ], "membership": "join", "messages": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "msgtype": "m.text" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } }, { "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": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state": [ { "content": { "join_rule": "public" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "state_key": "", "type": "m.room.join_rules", "unsigned": { "age": 1234, "membership": "join" } }, { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } }, { "content": { "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" }, "room_version": "11" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "state_key": "", "type": "m.room.create", "unsigned": { "age": 1234, "membership": "join" } }, { "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": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "state_key": "", "type": "m.room.power_levels", "unsigned": { "age": 1234, "membership": "join" } } ], "visibility": "private" } ] } } }, "schema": { "properties": { "account_data": { "description": "The global private data created by this user.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" }, "end": { "description": "A token which correlates to the end of the timelines returned. This\ntoken should be used with the `/events` endpoint to listen for new\nevents.", "type": "string" }, "presence": { "description": "A list of presence events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" }, "rooms": { "items": { "properties": { "account_data": { "description": "The private data that this user has attached to\nthis room.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" }, "invite": { "allOf": [ { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } ], "description": "The invite event if `membership` is `invite`", "title": "InviteEvent", "type": "object" }, "membership": { "description": "The user's membership state in this room.", "enum": [ "invite", "join", "leave", "ban" ], "type": "string" }, "messages": { "description": "The pagination chunk for this room.", "properties": { "chunk": { "description": "If the user is a member of the room this will be a\nlist of the most recent messages for this room. If\nthe user has left the room this will be the\nmessages that preceded them leaving. This array\nwill consist of at most `limit` elements.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "end": { "description": "A token which correlates to the end of `chunk`.\nCan be passed to\n[`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages)\nto retrieve later events.", "type": "string" }, "start": { "description": "A token which correlates to the start of `chunk`.\nCan be passed to\n[`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages)\nto retrieve earlier events.\n\nIf no earlier events are available, this property may be omitted from\nthe response.", "type": "string" } }, "required": [ "end", "chunk" ], "title": "PaginationChunk", "type": "object" }, "room_id": { "description": "The ID of this room.", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "state": { "description": "If the user is a member of the room this will be the\ncurrent state of the room as a list of events. If the\nuser has left the room this will be the state of the\nroom when they left it.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "visibility": { "description": "Whether this room is visible to the `/publicRooms` API\nor not.", "enum": [ "private", "public" ], "type": "string" } }, "required": [ "room_id", "membership" ], "title": "RoomInfo", "type": "object" }, "type": "array" } }, "required": [ "end", "rooms", "presence" ], "type": "object" } } }, "description": "The user's current state." }, "404": { "description": "There is no avatar URL for this user or this user does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the user's current state.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/join/{roomIdOrAlias}": { "post": { "description": "*Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`.\n\nThis API starts a user's participation 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`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3initialsync)\nand [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) APIs.", "operationId": "joinRoom", "parameters": [ { "description": "The room identifier or alias to join.", "example": "#monkeys:matrix.org", "in": "path", "name": "roomIdOrAlias", "required": true, "schema": { "oneOf": [ { "format": "mx-room-id", "pattern": "^!", "type": "string" }, { "format": "mx-room-alias", "pattern": "^#", "type": "string" } ] } }, { "description": "The servers to attempt to join the room through. One of the servers\nmust be participating in the room.", "example": [ "matrix.org", "elsewhere.ca" ], "in": "query", "name": "via", "schema": { "items": { "format": "mx-server-name", "type": "string" }, "type": "array" }, "x-addedInMatrixVersion": "1.12" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "example": "Looking for support", "type": "string", "x-addedInMatrixVersion": "1.1" }, "third_party_signed": { "allOf": [ { "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", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "sender": { "description": "The Matrix ID of the user who issued the invite.", "example": "@alice:example.org", "format": "mx-user-id", "pattern": "^@", "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" } ], "description": "If 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." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "room_id": "!d41d8cd:matrix.org" } } }, "schema": { "properties": { "room_id": { "description": "The joined room ID.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } } }, "description": "The room has been joined.\n\nThe joined room ID must be returned in the `room_id` field." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to join the room. A meaningful `errcode`\nand 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.\n- The room is restricted and the user failed to satisfy any of the conditions." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Join the requesting user to a particular room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/joined_rooms": { "get": { "description": "This API returns a list of the user's current rooms.", "operationId": "getJoinedRooms", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "joined_rooms": [ "!foo:example.com" ] } } }, "schema": { "properties": { "joined_rooms": { "description": "The ID of each room in which the user has `joined` membership.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" } }, "required": [ "joined_rooms" ], "type": "object" } } }, "description": "A list of the rooms the user is in." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Lists the user's current rooms.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/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`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync). 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.", "example": "s72594_4483_1934", "in": "query", "name": "from", "required": true, "schema": { "type": "string" } }, { "description": "The desired end point of the list. Should be the `next_batch`\nfield from a recent call to [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) - typically the most recent\nsuch call. This may be used by the server as a hint to check its\ncaches are up to date.", "example": "s75689_5632_2435", "in": "query", "name": "to", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "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" } } }, "description": "The list of users who updated their devices." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Query users with recent device key updates.", "tags": [ "End-to-end encryption" ] } }, "/_matrix/client/v3/keys/claim": { "post": { "description": "Claims one-time keys for use in pre-key messages.\n\nThe request contains the user ID, device ID and algorithm name of the\nkeys that are required. If a key matching these requirements can be\nfound, the response contains it. The returned key is a one-time key\nif one is available, and otherwise a fallback key.\n\nOne-time keys are given out in the order that they were uploaded via\n[/keys/upload](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3keysupload). (All\nkeys uploaded within a given call to `/keys/upload` are considered\nequivalent in this regard; no ordering is specified within them.)\n\nServers must ensure that each one-time key is returned at most once,\nso when a key has been returned, no other request will ever return\nthe same key.", "operationId": "claimKeys", "requestBody": { "content": { "application/json": { "schema": { "properties": { "one_time_keys": { "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" } }, "patternProperties": { "^@": { "additionalProperties": { "description": "algorithm", "example": "signed_curve25519", "type": "string" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "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" } } }, "description": "Query defining the keys to be claimed", "required": true }, "responses": { "200": { "content": { "application/json": { "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": { "description": "One-time keys for the queried devices. A map from user ID, to a\nmap from devices to a map from `:` to the key object.\n\nSee the [key algorithms](https://spec.matrix.org/v1.19/client-server-api/#key-algorithms) section for information\non the Key Object format.\n\nIf necessary, the claimed key might be a fallback key. Fallback\nkeys are re-used by the server until replaced by the device.", "example": { "@alice:example.com": { "JLAFKJWSCS": { "signed_curve25519:AAAAHg": { "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", "signatures": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" } } } } } }, "patternProperties": { "^@": { "additionalProperties": { "additionalProperties": { "oneOf": [ { "type": "string" }, { "properties": { "key": { "description": "The key, encoded using unpadded base64.", "type": "string" }, "signatures": { "description": "Signature for the device. Mapped from user ID to signature object,\ncontaining mapping from _key signing identifier_ to the signature\n(see also: [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json))", "patternProperties": { "^@": { "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "required": [ "key", "signatures" ], "title": "KeyObject", "type": "object" } ] }, "description": "One-time public keys. The names of the properties should be in the format\n`:`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/v1.19/client-server-api/#key-algorithms).", "title": "OneTimeKeys", "type": "object" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "required": [ "one_time_keys" ], "type": "object" } } }, "description": "The claimed keys." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Claim one-time encryption keys.", "tags": [ "End-to-end encryption" ] } }, "/_matrix/client/v3/keys/device_signing/upload": { "post": { "description": "Publishes cross-signing keys for the user.\n\nThis API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api),\nexcept when used by an application service.\n\nUser-Interactive Authentication MUST be performed for regular clients, except in these cases:\n- there is no existing master signing key uploaded to the homeserver, OR\n- there is an existing master signing key and it exactly matches the\n master signing key provided in the request body. If there are any additional\n keys provided in the request (self-signing key, user-signing key) they MUST also\n match the existing keys stored on the server. In other words, the request contains\n no new keys.\n\nThis allows clients to freely upload one set of keys, but not modify/overwrite keys if\nthey already exist. Allowing clients to upload the same set of keys more than once\nmakes this endpoint idempotent in the case where the response is lost over the network,\nwhich would otherwise cause a UIA challenge upon retry.\n\n**NOTE:** \nWhen this endpoint requires User-Interactive Authentication,\nit uses the [`m.oauth`](https://spec.matrix.org/v1.19/client-server-api/#oauth-authentication)\nauthentication type if the access token was obtained\nvia the [OAuth 2.0 API](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-api).\n", "operationId": "uploadCrossSigningKeys", "requestBody": { "content": { "application/json": { "schema": { "example": { "auth": { "example_credential": "verypoorsharedsecret", "session": "xxxxx", "type": "example.type.foo" }, "master_key": { "keys": { "ed25519:base64+master+public+key": "base64+master+public+key" }, "usage": [ "master" ], "user_id": "@alice:example.com" }, "self_signing_key": { "keys": { "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+master+public+key": "signature+of+self+signing+key" } }, "usage": [ "self_signing" ], "user_id": "@alice:example.com" }, "user_signing_key": { "keys": { "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+master+public+key": "signature+of+user+signing+key" } }, "usage": [ "user_signing" ], "user_id": "@alice:example.com" } }, "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "type": "object" } ], "description": "Additional authentication information for the\nuser-interactive authentication API." }, "master_key": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "description": "Optional. The user\\'s master signing key." }, "self_signing_key": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "description": "Optional. The user\\'s self-signing key. Must be signed by\nthe accompanying master signing key, or by the user\\'s most recently\nuploaded master signing key if no master signing key is included in the\nrequest." }, "user_signing_key": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "description": "Optional. The user\\'s user-signing key. Must be signed by\nthe accompanying master signing key, or by the user\\'s most recently\nuploaded master signing key if no master signing key is included in the\nrequest." } }, "type": "object" } } }, "description": "The keys to be published.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "example": {}, "type": "object" } } }, "description": "The provided keys were successfully uploaded." }, "400": { "content": { "application/json": { "schema": { "example": { "errcode": "M_INVALID_SIGNATURE", "error": "Invalid signature" }, "type": "object" } } }, "description": "The input was invalid in some way. This can include one of the\nfollowing error codes:\n\n* `M_INVALID_SIGNATURE`: For example, the self-signing or\n user-signing key had an incorrect signature.\n* `M_MISSING_PARAM`: No master signing key is available." }, "403": { "content": { "application/json": { "schema": { "example": { "errcode": "M_FORBIDDEN", "error": "Key ID in use" }, "type": "object" } } }, "description": "The public key of one of the keys is the same as one of the user\\'s\ndevice IDs, or the request is not authorised for any other reason." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload cross-signing keys.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1", "x-changedInMatrixVersion": { "1.11": "UIA is not always required for this endpoint.", "1.17": "This endpoint no longer requires User-Interactive Authentication when used by an\napplication service." } } }, "/_matrix/client/v3/keys/query": { "post": { "description": "Returns the current devices and identity keys for the given users.", "operationId": "queryKeys", "requestBody": { "content": { "application/json": { "schema": { "properties": { "device_keys": { "description": "The keys to be downloaded. A map from user ID, to a list of\ndevice IDs, or to an empty list to indicate all devices for the\ncorresponding user.", "example": { "@alice:example.com": [] }, "patternProperties": { "^@": { "items": { "description": "device ID", "type": "string" }, "type": "array", "x-pattern-format": "mx-user-id" } }, "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": [ "device_keys" ], "type": "object" } } }, "description": "Query defining the keys to be downloaded", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "device_keys": { "description": "Information on the queried devices. A map from user ID, to a\nmap from device ID to device information. For each device,\nthe information returned will be the same as uploaded via\n`/keys/upload`, with the addition of an `unsigned`\nproperty.", "example": { "@alice:example.com": { "JLAFKJWSCS": { "algorithms": [ "m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2" ], "device_id": "JLAFKJWSCS", "keys": { "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" }, "signatures": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" } }, "unsigned": { "device_display_name": "Alice's mobile phone" }, "user_id": "@alice:example.com" } } }, "patternProperties": { "^@": { "additionalProperties": { "allOf": [ { "description": "Device identity keys", "properties": { "algorithms": { "description": "The encryption algorithms supported by this device.", "example": [ "m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2" ], "items": { "type": "string" }, "type": "array" }, "device_id": { "description": "The ID of the device these keys belong to. Must match the device ID used\nwhen logging in.", "example": "JLAFKJWSCS", "type": "string" }, "keys": { "additionalProperties": { "type": "string" }, "description": "Public identity keys. The names of the properties should be in the\nformat `:`. The keys themselves should be\nencoded as specified by the key algorithm.", "example": { "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" }, "type": "object" }, "signatures": { "description": "Signatures for the device key object. A map from user ID, to a map from\n`:` to the signature.\n\nThe signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).", "example": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" } }, "patternProperties": { "^@": { "additionalProperties": { "type": "string" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "title": "Signatures", "type": "object" }, "user_id": { "description": "The ID of the user the device belongs to. Must match the user ID used\nwhen logging in.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "device_id", "algorithms", "keys", "signatures" ], "title": "DeviceKeys", "type": "object" } ], "properties": { "unsigned": { "description": "Additional data added to the device key information\nby intermediate servers, and not covered by the\nsignatures.", "properties": { "device_display_name": { "description": "The display name which the user set on the device.", "type": "string" } }, "title": "UnsignedDeviceInfo", "type": "object" } }, "title": "DeviceInformation" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" }, "failures": { "additionalProperties": { "type": "object" }, "description": "If any remote homeservers could not be reached, they are\nrecorded here. The names of the properties are the names of\nthe unreachable servers.\n\nIf the homeserver could be reached, but the user or device\nwas unknown, no failure is recorded. Instead, the corresponding\nuser or device is missing from the `device_keys` result.", "example": {}, "type": "object" }, "master_keys": { "description": "Information on the master signing keys of the queried users.\nA map from user ID, to master signing key information. For each key, the\ninformation returned will be the same as uploaded via\n`/keys/device_signing/upload`, along with the signatures\nuploaded via `/keys/signatures/upload` that the requesting user\nis allowed to see.", "example": { "@alice:example.com": { "keys": { "ed25519:base64+master+public+key": "base64+master+public+key" }, "usage": [ "master" ], "user_id": "@alice:example.com" } }, "patternProperties": { "^@": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "x-pattern-format": "mx-user-id" } }, "type": "object", "x-addedInMatrixVersion": "1.1" }, "self_signing_keys": { "description": "Information on the self-signing keys of the queried users. A map\nfrom user ID, to self-signing key information. For each key, the\ninformation returned will be the same as uploaded via\n`/keys/device_signing/upload`.", "example": { "@alice:example.com": { "keys": { "ed25519:base64+self+signing+public+key": "base64+self+signing+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+master+public+key": "signature+of+self+signing+key" } }, "usage": [ "self_signing" ], "user_id": "@alice:example.com" } }, "patternProperties": { "^@": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "x-pattern-format": "mx-user-id" } }, "type": "object", "x-addedInMatrixVersion": "1.1" }, "user_signing_keys": { "description": "Information on the user-signing key of the user making the\nrequest, if they queried their own device information. A map\nfrom user ID, to user-signing key information. The\ninformation returned will be the same as uploaded via\n`/keys/device_signing/upload`.", "example": { "@alice:example.com": { "keys": { "ed25519:base64+user+signing+public+key": "base64+user+signing+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+master+public+key": "signature+of+user+signing+key" } }, "usage": [ "user_signing" ], "user_id": "@alice:example.com" } }, "patternProperties": { "^@": { "allOf": [ { "description": "Key used for cross signing", "properties": { "keys": { "additionalProperties": { "type": "string" }, "description": "The public key. The object must have exactly one property, whose name is\nin the form `:`, and whose value\nis the unpadded base64 public key.", "example": { "ed25519:alice+base64+public+key": "alice+base64+public+key" }, "maxProperties": 1, "minProperties": 1, "type": "object" }, "signatures": { "description": "Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).\nOptional for the master signing key. Other keys must be signed by the\nuser\\'s master signing key.", "example": { "@alice:example.com": { "ed25519:alice+base64+master+key": "signature+of+key" } }, "title": "Signatures", "type": "object" }, "usage": { "description": "What the key is used for.", "items": { "enum": [ "master", "self_signing", "user_signing" ], "type": "string" }, "type": "array" }, "user_id": { "description": "The ID of the user the key belongs to.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "usage", "keys" ], "title": "CrossSigningKey", "type": "object" } ], "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "type": "object" } } }, "description": "The device information" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Download device identity keys.", "tags": [ "End-to-end encryption" ] } }, "/_matrix/client/v3/keys/signatures/upload": { "post": { "description": "Publishes cross-signing signatures for the user.\n\nThe signed JSON object must match the key previously uploaded or\nretrieved for the given key ID, with the exception of the `signatures`\nproperty, which contains the new signature(s) to add.", "operationId": "uploadCrossSigningSignatures", "requestBody": { "content": { "application/json": { "schema": { "description": "A map of user ID to a map of key ID to signed JSON object.", "example": { "@alice:example.com": { "HIJKLMN": { "algorithms": [ "m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2" ], "device_id": "HIJKLMN", "keys": { "curve25519:HIJKLMN": "base64+curve25519+key", "ed25519:HIJKLMN": "base64+ed25519+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+self+signing+public+key": "base64+signature+of+HIJKLMN" } }, "user_id": "@alice:example.com" }, "base64+master+public+key": { "keys": { "ed25519:base64+master+public+key": "base64+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:HIJKLMN": "base64+signature+of+master+key" } }, "usage": [ "master" ], "user_id": "@alice:example.com" } }, "@bob:example.com": { "bobs+base64+master+public+key": { "keys": { "ed25519:bobs+base64+master+public+key": "bobs+base64+master+public+key" }, "signatures": { "@alice:example.com": { "ed25519:base64+user+signing+public+key": "base64+signature+of+bobs+master+key" } }, "usage": [ "master" ], "user_id": "@bob:example.com" } } }, "patternProperties": { "^@": { "additionalProperties": { "type": "object" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } } }, "description": "A map from user ID to key ID to signed JSON objects containing the\nsignatures to be published.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "failures": { "description": "A map from user ID to key ID to an error for any signatures\nthat failed. If a signature was invalid, the `errcode` will\nbe set to `M_INVALID_SIGNATURE`.", "example": { "@alice:example.com": { "HIJKLMN": { "errcode": "M_INVALID_SIGNATURE", "error": "Invalid signature" } } }, "patternProperties": { "^@": { "additionalProperties": { "title": "Error", "type": "object" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "type": "object" } } }, "description": "The provided signatures were processed." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload cross-signing signatures.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/keys/upload": { "post": { "description": "Publishes end-to-end encryption keys for the device.", "operationId": "uploadKeys", "requestBody": { "content": { "application/json": { "schema": { "properties": { "device_keys": { "allOf": [ { "description": "Device identity keys", "properties": { "algorithms": { "description": "The encryption algorithms supported by this device.", "example": [ "m.olm.v1.curve25519-aes-sha2", "m.megolm.v1.aes-sha2" ], "items": { "type": "string" }, "type": "array" }, "device_id": { "description": "The ID of the device these keys belong to. Must match the device ID used\nwhen logging in.", "example": "JLAFKJWSCS", "type": "string" }, "keys": { "additionalProperties": { "type": "string" }, "description": "Public identity keys. The names of the properties should be in the\nformat `:`. The keys themselves should be\nencoded as specified by the key algorithm.", "example": { "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" }, "type": "object" }, "signatures": { "description": "Signatures for the device key object. A map from user ID, to a map from\n`:` to the signature.\n\nThe signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json).", "example": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" } }, "patternProperties": { "^@": { "additionalProperties": { "type": "string" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "title": "Signatures", "type": "object" }, "user_id": { "description": "The ID of the user the device belongs to. Must match the user ID used\nwhen logging in.", "example": "@alice:example.com", "type": "string" } }, "required": [ "user_id", "device_id", "algorithms", "keys", "signatures" ], "title": "DeviceKeys", "type": "object" } ], "description": "Identity keys for the device. May be absent if no new\nidentity keys are required." }, "fallback_keys": { "allOf": [ { "additionalProperties": { "oneOf": [ { "type": "string" }, { "properties": { "key": { "description": "The key, encoded using unpadded base64.", "type": "string" }, "signatures": { "description": "Signature for the device. Mapped from user ID to signature object,\ncontaining mapping from _key signing identifier_ to the signature\n(see also: [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json))", "patternProperties": { "^@": { "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "required": [ "key", "signatures" ], "title": "KeyObject", "type": "object" } ] }, "description": "One-time public keys. The names of the properties should be in the format\n`:`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/v1.19/client-server-api/#key-algorithms).", "title": "OneTimeKeys", "type": "object" } ], "description": "The public key which should be used if the device's one-time keys\nare exhausted. The fallback key is not deleted once used, but should\nbe replaced when additional one-time keys are being uploaded. The\nserver will notify the client of the fallback key being used through\n`/sync`.\n\nThere can only be at most one key per algorithm uploaded, and the server\nwill only persist one key per algorithm.\n\nWhen uploading a signed key, an additional `fallback: true` key should\nbe included to denote that the key is a fallback key.\n\nMay be absent if a new fallback key is not required.", "example": { "signed_curve25519:AAAAGj": { "fallback": true, "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", "signatures": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" } } } }, "type": "object", "x-addedInMatrixVersion": "1.2" }, "one_time_keys": { "allOf": [ { "additionalProperties": { "oneOf": [ { "type": "string" }, { "properties": { "key": { "description": "The key, encoded using unpadded base64.", "type": "string" }, "signatures": { "description": "Signature for the device. Mapped from user ID to signature object,\ncontaining mapping from _key signing identifier_ to the signature\n(see also: [Signing JSON](https://spec.matrix.org/v1.19/appendices/#signing-json))", "patternProperties": { "^@": { "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "required": [ "key", "signatures" ], "title": "KeyObject", "type": "object" } ] }, "description": "One-time public keys. The names of the properties should be in the format\n`:`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/v1.19/client-server-api/#key-algorithms).", "title": "OneTimeKeys", "type": "object" } ], "description": "One-time public keys for \"pre-key\" messages. The names of\nthe properties should be in the format\n`:`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/v1.19/client-server-api/#key-algorithms).\n\nMay be absent if no new one-time keys are required.", "example": { "signed_curve25519:AAAAHQ": { "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", "signatures": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" } } }, "signed_curve25519:AAAAHg": { "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", "signatures": { "@alice:example.com": { "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" } } } }, "type": "object" } }, "type": "object" } } }, "description": "The keys to be published", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "one_time_key_counts": { "additionalProperties": { "type": "integer" }, "description": "For each key algorithm, the number of unclaimed one-time keys\nof that type currently held on the server for this device.\nIf an algorithm is not listed, the count for that algorithm\nis to be assumed zero.", "example": { "signed_curve25519": 20 }, "type": "object" } }, "required": [ "one_time_key_counts" ], "type": "object" } } }, "description": "The provided keys were successfully uploaded." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload end-to-end encryption keys.", "tags": [ "End-to-end encryption" ] } }, "/_matrix/client/v3/knock/{roomIdOrAlias}": { "post": { "description": "*Note that this API takes either a room ID or alias, unlike other membership APIs.*\n\nThis API \"knocks\" on the room to ask for permission to join, if the user\nis allowed to knock on the room. Acceptance of the knock happens out of\nband from this API, meaning that the client will have to watch for updates\nregarding the acceptance/rejection of the knock.\n\nIf the room history settings allow, the user will still be able to see\nhistory of the room while being in the \"knock\" state. The user will have\nto accept the invitation to join the room (acceptance of knock) to see\nmessages reliably. See the `/join` endpoints for more information about\nhistory visibility to the user.\n\nThe knock will appear as an entry in the response of the\n[`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) API.", "operationId": "knockRoom", "parameters": [ { "description": "The room identifier or alias to knock upon.", "example": "#monkeys:matrix.org", "in": "path", "name": "roomIdOrAlias", "required": true, "schema": { "oneOf": [ { "format": "mx-room-id", "pattern": "^!", "type": "string" }, { "format": "mx-room-alias", "pattern": "^#", "type": "string" } ] } }, { "description": "The servers to attempt to knock on the room through. One of the servers\nmust be participating in the room.", "example": [ "matrix.org", "elsewhere.ca" ], "in": "query", "name": "via", "schema": { "items": { "format": "mx-server-name", "type": "string" }, "type": "array" }, "x-addedInMatrixVersion": "1.12" } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "example": "Looking for support", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "room_id": "!d41d8cd:matrix.org" } } }, "schema": { "properties": { "room_id": { "description": "The knocked room ID.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } } }, "description": "The room has been knocked upon.\n\nThe knocked room ID must be returned in the `room_id` field." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "You are not allowed to knock on 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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to knock on the room. A meaningful `errcode`\nand description error text will be returned. Example reasons for rejection are:\n\n- The room is not set up for knocking.\n- The user has been banned from the room." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "That room does not appear to exist." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The room could not be found or resolved to a room ID." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Knock on a room, requesting permission to join.", "tags": [ "Room membership" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/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": { "content": { "application/json": { "examples": { "response": { "value": { "flows": [ { "type": "m.login.password" }, { "get_login_token": true, "type": "m.login.token" } ] } } }, "schema": { "properties": { "flows": { "description": "The homeserver's supported login types", "items": { "properties": { "get_login_token": { "description": "If `type` is `m.login.token`, an optional field to indicate\nto the unauthenticated client that the homeserver supports\nthe [`POST /login/get_token`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv1loginget_token)\nendpoint. Note that supporting the endpoint does not\nnecessarily indicate that the user attempting to log in will\nbe able to generate such a token.", "type": "boolean", "x-addedInMatrixVersion": "1.7" }, "type": { "description": "The login type. This is supplied as the `type` when\nlogging in.", "type": "string" } }, "required": [ "type" ], "title": "LoginFlow", "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The login types the homeserver supports" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_UNRECOGNIZED", "error": "OAuth 2.0 authentication is in use on this homeserver." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "With `M_UNRECOGNIZED`: the homeserver does not support the legacy authentication API.\n(See [Authentication API discovery](https://spec.matrix.org/v1.19/client-server-api/#authentication-api-discovery).)" }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "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 authorise 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](https://spec.matrix.org/v1.19/client-server-api/#relationship-between-access-tokens-and-devices).", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "example": { "identifier": { "type": "m.id.user", "user": "cheeky_monkey" }, "initial_device_display_name": "Jungle Phone", "password": "ilovebananas", "type": "m.login.password" }, "properties": { "address": { "deprecated": true, "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 given\ndevice ID must not be the same as a\n[cross-signing](https://spec.matrix.org/v1.19/client-server-api/#cross-signing) key ID.\nThe server will auto-generate a `device_id`\nif this is not specified.", "type": "string" }, "identifier": { "additionalProperties": { "description": "Keys dependent on the identification type." }, "description": "Identification information for a user", "properties": { "type": { "description": "The type of identification. See [Identifier types](https://spec.matrix.org/v1.19/client-server-api/#identifier-types)\nfor 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": { "deprecated": true, "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" }, "refresh_token": { "description": "If true, the client supports refresh tokens.", "type": "boolean", "x-addedInMatrixVersion": "1.3" }, "token": { "description": "Required when `type` is `m.login.token`. Part of Token-based login.", "type": "string" }, "type": { "description": "The login type being used.\n\nThis must be a type returned in one of the flows of the\nresponse of the [`GET /login`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3login)\nendpoint, like `m.login.password` or `m.login.token`.", "type": "string" }, "user": { "deprecated": true, "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "access_token": "abc123", "device_id": "GHTYAJCE", "expires_in_ms": 60000, "refresh_token": "def456", "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 authorise 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" }, "expires_in_ms": { "description": "The lifetime of the access token, in milliseconds. Once\nthe access token has expired a new access token can be\nobtained by using the provided refresh token. If no\nrefresh token is provided, the client will need to re-log in\nto obtain a new access token. If not given, the client can\nassume that the access token will not expire.", "type": "integer", "x-addedInMatrixVersion": "1.3" }, "home_server": { "deprecated": true, "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.", "format": "mx-server-name", "type": "string" }, "refresh_token": { "description": "A refresh token for the account. This token can be used to\nobtain a new access token when it expires by calling the\n`/refresh` endpoint.", "type": "string", "x-addedInMatrixVersion": "1.3" }, "user_id": { "description": "The fully-qualified Matrix ID for the account.", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "well_known": { "allOf": [ { "additionalProperties": { "description": "Application-dependent keys using Java package naming convention." }, "description": "Used by clients to determine the homeserver, identity server, and other\noptional components they should be interacting with.", "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", "format": "uri", "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", "format": "uri", "type": "string" } }, "required": [ "base_url" ], "title": "Identity Server Information", "type": "object" } }, "required": [ "m.homeserver" ], "title": "Discovery Information", "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." } }, "required": [ "access_token", "device_id", "user_id" ], "type": "object" } } }, "description": "The user has been authenticated." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "Part of the request was invalid. For example, the login type may not be recognised.\n\nSpecific error codes used with this status code include:\n * **[Added in `v1.17`]** `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service\n used the `m.login.application_service` type, but the server doesn't support logging\n in via the Legacy authentication API." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The login attempt failed. This can include one of the following error codes:\n * `M_FORBIDDEN`: The provided authentication data was incorrect\n or the requested device ID is the same as a cross-signing key\n ID.\n * `M_USER_DEACTIVATED`: The user has been deactivated.\n Servers MAY instead use `M_FORBIDDEN` when they can no longer authenticate\n the deactivated user (e.g. their password has been wiped)." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "summary": "Authenticates the user.", "tags": [ "Session management" ] } }, "/_matrix/client/v3/login/sso/redirect": { "get": { "description": "A web-based Matrix client should instruct the user's browser to\nnavigate to this endpoint in order to log in via SSO.\n\nThe server MUST respond with an HTTP redirect to the SSO interface,\nor present a page which lets the user select an IdP to continue\nwith in the event multiple are supported by the server.", "operationId": "redirectToSSO", "parameters": [ { "description": "URI to which the user will be redirected after the homeserver has\nauthenticated the user with SSO.", "in": "query", "name": "redirectUrl", "required": true, "schema": { "type": "string" } }, { "description": "The action that the user wishes to take at the SSO redirect.\n\nThe following values are supported:\n * `login`: the SSO redirect is for the purposes of signing an\n existing user in.\n * `register`: the SSO redirect is for the purpose of registering a\n new user account.", "in": "query", "name": "action", "schema": { "enum": [ "login", "register" ], "type": "string" }, "x-addedInMatrixVersion": "1.18" } ], "responses": { "302": { "description": "A redirect to the SSO interface.", "headers": { "Location": { "schema": { "type": "string" } } } } }, "summary": "Redirect the user's browser to the SSO interface.", "tags": [ "Session management" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/login/sso/redirect/{idpId}": { "get": { "description": "This endpoint is the same as `/login/sso/redirect`, though with an\nIdP ID from the original `identity_providers` array to inform the\nserver of which IdP the client/user would like to continue with.\n\nThe server MUST respond with an HTTP redirect to the SSO interface\nfor that IdP.", "operationId": "redirectToIdP", "parameters": [ { "description": "The `id` of the IdP from the `m.login.sso` `identity_providers`\narray denoting the user's selection.", "in": "path", "name": "idpId", "required": true, "schema": { "type": "string" } }, { "description": "URI to which the user will be redirected after the homeserver has\nauthenticated the user with SSO.", "in": "query", "name": "redirectUrl", "required": true, "schema": { "type": "string" } }, { "description": "The action that the user wishes to take at the SSO redirect.\n\nThe following values are supported:\n * `login`: the SSO redirect is for the purposes of signing an\n existing user in.\n * `register`: the SSO redirect is for the purpose of registering a\n new user account.", "in": "query", "name": "action", "schema": { "enum": [ "login", "register" ], "type": "string" }, "x-addedInMatrixVersion": "1.18" } ], "responses": { "302": { "description": "A redirect to the SSO interface.", "headers": { "Location": { "schema": { "type": "string" } } } }, "404": { "description": "The IdP ID was not recognized by the server. The server is encouraged\nto provide a user-friendly page explaining the error given the user\nwill be navigated to it." } }, "summary": "Redirect the user's browser to the SSO interface for an IdP.", "tags": [ "Session management" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/logout": { "post": { "description": "Invalidates an existing access token, so that it can no longer be used for\nauthorisation. The device associated with the access token is also deleted.\n[Device keys](https://spec.matrix.org/v1.19/client-server-api/#device-keys) for the device are deleted alongside the device.", "operationId": "logout", "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "The access token used in the request was successfully invalidated." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Invalidates a user access token", "tags": [ "Session management" ] } }, "/_matrix/client/v3/logout/all": { "post": { "description": "Invalidates all access tokens for a user, so that they can no longer be used for\nauthorisation. This includes the access token that made this request. All devices\nfor the user are also deleted. [Device keys](https://spec.matrix.org/v1.19/client-server-api/#device-keys) for the device are\ndeleted alongside the device.\n\nThis endpoint does not use the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#user-interactive-authentication-api) because\nUser-Interactive Authentication is designed to protect against attacks where\nsomeone gets hold of a single access token then takes over the account. This\nendpoint invalidates all access tokens for the user, including the token used in\nthe request, and therefore the attacker is unable to take over the account in\nthis way.", "operationId": "logout_all", "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "The user's access tokens were successfully invalidated." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Invalidates all access tokens for a user", "tags": [ "Session management" ] } }, "/_matrix/client/v3/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 to continue from. This should be the `next_token`\nreturned from an earlier call to this endpoint.", "example": "xxxxx", "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "description": "Limit on the number of events to return in this request.", "example": 20, "in": "query", "name": "limit", "required": false, "schema": { "type": "integer" } }, { "description": "Allows basic filtering of events returned. Supply `highlight`\nto return only events where the notification had the highlight\ntweak set.", "example": "highlight", "in": "query", "name": "only", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "next_token": "abcdef", "notifications": [ { "actions": [ "notify" ], "event": { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } }, "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](https://spec.matrix.org/v1.19/client-server-api/#push-rules-api).", "items": { "type": [ "object", "string" ] }, "type": "array" }, "event": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" } ], "description": "The Event object for the event that triggered the notification.", "title": "Event" }, "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.", "format": "int64", "type": "integer" } }, "required": [ "actions", "event", "read", "room_id", "ts" ], "title": "Notification", "type": "object" }, "type": "array" } }, "required": [ "notifications" ], "type": "object" } } }, "description": "A batch of events is being returned" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets a list of events that the user has been notified about", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/presence/{userId}/status": { "get": { "description": "Get the given user's presence state.", "operationId": "getPresence", "parameters": [ { "description": "The user whose presence state to get.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "last_active_ago": 420845, "presence": "unavailable" } } }, "schema": { "properties": { "currently_active": { "description": "Whether the user is currently active", "type": "boolean" }, "last_active_ago": { "description": "The length of time in milliseconds since an action was performed\nby this user.", "type": "integer" }, "presence": { "description": "This user's presence.", "enum": [ "online", "offline", "unavailable" ], "type": "string" }, "status_msg": { "description": "The state message for this user if one was set.", "type": [ "string", "null" ] } }, "required": [ "presence" ], "type": "object" } } }, "description": "The presence state for this user." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You are not allowed to see this user's presence status." }, "404": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "description": "There is no presence state for this user. This user may not exist or\nisn't exposing presence information to you." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "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" } } }, "description": "The updated presence state.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The new presence state was set." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Update this user's presence state.", "tags": [ "Presence" ] } }, "/_matrix/client/v3/profile/{userId}": { "get": { "description": "Get the complete profile for a user.", "operationId": "getUserProfile", "parameters": [ { "description": "The user whose profile information to get.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "avatar_url": "mxc://matrix.org/SDGdghriugerRg", "displayname": "Alice Margatroid", "m.example_field": "custom_value", "m.tz": "Europe/London" } } }, "schema": { "additionalProperties": { "description": "Additional profile fields.", "x-addedInMatrixVersion": "1.16" }, "properties": { "avatar_url": { "description": "The user's avatar URL if they have set one, otherwise not present.", "format": "mx-mxc-uri", "type": "string" }, "displayname": { "description": "The user's display name if they have set one, otherwise not present.", "type": "string" }, "m.tz": { "description": "The user's time zone.", "type": "string", "x-addedInMatrixVersion": "1.16" } }, "type": "object" } } }, "description": "The profile information for this user." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Profile lookup is disabled on this homeserver" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The server is unwilling to disclose whether the user exists and/or has profile information.", "x-addedInMatrixVersion": "1.2" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Profile 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" ], "title": "Error", "type": "object" } } }, "description": "There is no profile information for this user or this user does not exist." } }, "summary": "Get all profile information for a user.", "tags": [ "User data" ] } }, "/_matrix/client/v3/profile/{userId}/{keyName}": { "delete": { "description": "Remove a specific field from a user's profile.", "operationId": "deleteProfileField", "parameters": [ { "description": "The user whose profile field should be deleted.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "The name of the profile field to delete.", "example": "displayname", "in": "path", "name": "keyName", "required": true, "schema": { "pattern": "^(avatar_url|displayname|m\\.tz|[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The profile field was deleted or it doesn't exist." }, "400": { "content": { "application/json": { "examples": { "bad_json": { "value": { "errcode": "M_BAD_JSON", "error": "Malformed request." } }, "invalid_key": { "value": { "errcode": "M_INVALID_PARAM", "error": "Invalid profile key." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The request is malformed, contains invalid JSON, or specifies an invalid key." }, "403": { "content": { "application/json": { "examples": { "forbidden": { "value": { "errcode": "M_FORBIDDEN", "error": "Profile deletion is not permitted." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user is not authorised to delete this profile field." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Remove a profile field from a user.", "tags": [ "User data" ], "x-addedInMatrixVersion": "1.16" }, "get": { "description": "Get the value of a profile field for a user.", "operationId": "getProfileField", "parameters": [ { "description": "The user whose profile field should be returned.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "The name of the profile field to retrieve.", "example": "displayname", "in": "path", "name": "keyName", "required": true, "schema": { "pattern": "^(avatar_url|displayname|m\\.tz|[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "displayname": "Alice" } } }, "schema": { "additionalProperties": true, "description": "An object with one property, whose key matches the `keyName` specified\nin the URL, and whose value is the current setting of that profile field.\n", "type": "object" } } }, "description": "The profile field value was retrieved." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Profile lookup is disabled on this homeserver" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The server is unwilling to disclose whether the user exists and/or has the specified profile field.", "x-addedInMatrixVersion": "1.12" }, "404": { "description": "There is no profile field with this key for this user, or the user does not exist." } }, "summary": "Get a profile field for a user.", "tags": [ "User data" ], "x-changedInMatrixVersion": { "1.16": "This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted." } }, "put": { "description": "Set or update a profile field for a user. Must be authenticated with an\naccess token authorised to make changes. Servers MAY impose size limits\non individual fields, and the total profile MUST be under 64 KiB.\n\nServers MAY reject `null` values. Servers that accept `null` values SHOULD store\nthem rather than treating `null` as a deletion request. Clients that want to delete a\nfield, including its key and value, SHOULD use the `DELETE` endpoint instead.\n\nThis endpoint uses [capabilities negotiation](https://spec.matrix.org/v1.19/client-server-api/#capabilities-negotiation)\ndepending on the `keyName`. Clients SHOULD check the value of the\n[`m.profile_fields` capability](https://spec.matrix.org/v1.19/client-server-api/#mprofile_fields-capability) to detect\nwhich `keyName`s they are allowed to modify.", "operationId": "setProfileField", "parameters": [ { "description": "The user whose profile field should be set.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "The name of the profile field to set. This MUST be either `avatar_url`, `displayname`, `m.tz`, or a custom field following the [Common Namespaced Identifier Grammar](https://spec.matrix.org/v1.19/appendices/#common-namespaced-identifier-grammar).", "example": "displayname", "in": "path", "name": "keyName", "required": true, "schema": { "pattern": "^(avatar_url|displayname|m\\.tz|[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "description": "An object which contains exactly one property. The key\nof that property MUST match the `keyName` specified in the URL.\n\nFor `avatar_url`, the value MUST be an MXC URI string.\n\nFor `displayname`, the value MUST be a string.\n\nFor `m.tz`, the value MUST be a valid identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).\nServers MAY choose to validate the value. Clients MUST expect unknown or invalid\nvalues.\n\nFor custom keys, any JSON type is allowed. Servers MAY not validate\nthese values, but clients SHOULD follow the format defined for that key.\n", "example": { "displayname": "Alice Wonderland" }, "minProperties": 1, "type": "object" } } }, "description": "A JSON object containing the property whose name matches the `keyName` specified in the URL. See `additionalProperties` for further details.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The profile field was set." }, "400": { "content": { "application/json": { "examples": { "bad_json": { "value": { "errcode": "M_BAD_JSON", "error": "Malformed JSON payload." } }, "invalid_key": { "value": { "errcode": "M_INVALID_PARAM", "error": "Invalid profile key." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The input was invalid in some way. This can include one\nof the following error codes:\n\n- `M_BAD_JSON`: The provided value is not valid JSON.\n- `M_MISSING_PARAM`: The required `keyName` property is\n missing from the request body.\n- `M_PROFILE_TOO_LARGE`: Storing the supplied value would\n make the profile exceed its maximum allowed size of 64 KiB.\n- `M_KEY_TOO_LARGE`: The supplied profile key exceeds the\n maximum allowed key length of 255 bytes.\n" }, "403": { "content": { "application/json": { "examples": { "forbidden": { "value": { "errcode": "M_FORBIDDEN", "error": "Profile modification is not permitted." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The server is unwilling to perform the operation, either due to insufficient permissions or because profile modifications are disabled." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set a profile field for a user.", "tags": [ "User data" ], "x-changedInMatrixVersion": { "1.16": "This endpoint now accepts a variable `keyName` parameter and `m.tz` was added as a defined key. Previously only `displayname` and `avatar_url` were accepted." } } }, "/_matrix/client/v3/publicRooms": { "get": { "description": "Lists a server's published room directory.\n\nThis API returns paginated responses.\n\n**[Changed in `v1.19`]** The server determines the order of the rooms\nreturned by this endpoint. Previously, rooms were ordered with the largest\njoined member count first. Continuing to order by largest first or another\nstable order is recommended.", "operationId": "getPublicRooms", "parameters": [ { "description": "Limit the number of results returned.", "in": "query", "name": "limit", "schema": { "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", "schema": { "type": "string" } }, { "description": "The server to fetch the published room directory from. Defaults\nto the local server. Case sensitive.", "in": "query", "name": "server", "schema": { "format": "mx-server-name", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of the published rooms on the server.", "example": { "chunk": [ { "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", "guest_can_join": false, "join_rule": "public", "name": "CHEESE", "num_joined_members": 37, "room_id": "!ol19s:bleecker.street", "room_type": "m.space", "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 published rooms.", "items": { "properties": { "avatar_url": { "description": "The URL for the room's avatar, if one is set.", "example": "mxc://example.org/abcdef", "format": "uri", "type": "string" }, "canonical_alias": { "description": "The canonical alias of the room, if any.", "example": "#general:example.org", "format": "mx-room-alias", "pattern": "^#", "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.", "example": true, "type": "boolean" }, "join_rule": { "description": "The room's join rule. When not present, the room is assumed to\nbe `public`.", "example": "public", "type": "string" }, "name": { "description": "The name of the room, if any.", "example": "General Chat", "type": "string" }, "num_joined_members": { "description": "The number of members joined to the room.", "example": 42, "type": "integer" }, "room_id": { "description": "The ID of the room.", "example": "!abcdefg:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "topic": { "description": "The plain text topic of the room. Omitted if no `text/plain` mimetype\nexists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).", "example": "All things general", "type": "string" }, "world_readable": { "description": "Whether the room may be viewed by users without joining.", "example": false, "type": "boolean" } }, "required": [ "room_id", "num_joined_members", "world_readable", "guest_can_join" ], "title": "PublishedRoomsChunk", "type": "object" }, "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 published rooms, if the\nserver has an estimate.", "type": "integer" } }, "required": [ "chunk" ], "type": "object" } } }, "description": "A list of the published rooms on the server." } }, "summary": "Lists a server's published room directory", "tags": [ "Room discovery" ] }, "post": { "description": "Lists a server's published room directory with an optional filter.\n\nThis API returns paginated responses.\n\n**[Changed in `v1.19`]** The server determines the order of the rooms\nreturned by this endpoint. Previously, rooms were ordered with the largest\njoined member count first. Continuing to order by largest first or another\nstable order is recommended.", "operationId": "queryPublicRooms", "parameters": [ { "description": "The server to fetch the published room directory from. Defaults\nto the local server. Case sensitive.", "in": "query", "name": "server", "schema": { "format": "mx-server-name", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "filter": { "generic_search_term": "foo", "room_types": [ null, "m.space" ] }, "include_all_networks": false, "limit": 10, "third_party_instance_id": "irc-freenode" }, "properties": { "filter": { "description": "Filter to apply to the results.", "properties": { "generic_search_term": { "description": "An optional string to search for in the room metadata, e.g. name,\ntopic, canonical alias, etc.", "type": "string" }, "room_types": { "description": "An optional list of [room types](https://spec.matrix.org/v1.19/client-server-api/#types) to search\nfor. To include rooms without a room type, specify `null` within this\nlist. When not specified, all applicable rooms (regardless of type)\nare returned.", "items": { "type": [ "string", "null" ] }, "type": "array", "x-addedInMatrixVersion": "1.4" } }, "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.\n\nThis is the `instance_id` of a `Protocol Instance` returned by\n[`GET /_matrix/client/v3/thirdparty/protocols`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3thirdpartyprotocols).", "example": "irc", "type": "string" } }, "type": "object" } } }, "description": "Options for which rooms to return.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "description": "A list of the published rooms on the server.", "example": { "chunk": [ { "avatar_url": "mxc://bleecker.street/CHEDDARandBRIE", "guest_can_join": false, "join_rule": "public", "name": "CHEESE", "num_joined_members": 37, "room_id": "!ol19s:bleecker.street", "room_type": "m.space", "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 published rooms.", "items": { "properties": { "avatar_url": { "description": "The URL for the room's avatar, if one is set.", "example": "mxc://example.org/abcdef", "format": "uri", "type": "string" }, "canonical_alias": { "description": "The canonical alias of the room, if any.", "example": "#general:example.org", "format": "mx-room-alias", "pattern": "^#", "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.", "example": true, "type": "boolean" }, "join_rule": { "description": "The room's join rule. When not present, the room is assumed to\nbe `public`.", "example": "public", "type": "string" }, "name": { "description": "The name of the room, if any.", "example": "General Chat", "type": "string" }, "num_joined_members": { "description": "The number of members joined to the room.", "example": 42, "type": "integer" }, "room_id": { "description": "The ID of the room.", "example": "!abcdefg:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "room_type": { "description": "The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.19/client-server-api/#mroomcreate)), if any.", "type": "string" }, "topic": { "description": "The plain text topic of the room. Omitted if no `text/plain` mimetype\nexists in [`m.room.topic`](https://spec.matrix.org/v1.19/client-server-api/#mroomtopic).", "example": "All things general", "type": "string" }, "world_readable": { "description": "Whether the room may be viewed by users without joining.", "example": false, "type": "boolean" } }, "required": [ "room_id", "num_joined_members", "world_readable", "guest_can_join" ], "title": "PublishedRoomsChunk", "type": "object" }, "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 published rooms, if the\nserver has an estimate.", "type": "integer" } }, "required": [ "chunk" ], "type": "object" } } }, "description": "A filtered list of the published rooms on the server." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Lists a server's published room directory with an optional filter", "tags": [ "Room discovery" ] } }, "/_matrix/client/v3/pushers": { "get": { "description": "Gets all currently active pushers for the authenticated user.", "operationId": "getPushers", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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.", "format": "uri", "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" } } }, "description": "The pushers for this user." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets the current pushers for the authenticated user", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushers/set": { "post": { "description": "This endpoint allows the creation, modification and deletion of [pushers](https://spec.matrix.org/v1.19/client-server-api/#push-notifications)\nfor this user ID. The behaviour of this endpoint varies depending on the\nvalues in the JSON body.\n\nIf `kind` is not `null`, the pusher with this `app_id` and `pushkey`\nfor this user is updated, or it is created if it doesn't exist. If\n`kind` is `null`, the pusher with this `app_id` and `pushkey` for this\nuser is deleted.", "operationId": "postPusher", "requestBody": { "content": { "application/json": { "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": "Required if `kind` is not `null`. A string that will allow the\nuser to identify what application owns 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": "Required if `kind` is not `null`. A dictionary of information\nfor the pusher implementation itself.\n\nIf `kind` is `http`, this MUST contain `url` which is the URL\nto use for sending notifications. Clients MAY use this object\nto pass custom data to their push gateway. Servers MUST forward\nthe entire content including `format` and any custom keys but excluding `url`\nwhen calling [`/_matrix/push/v1/notify`](https://spec.matrix.org/v1.19/push-gateway-api/#post_matrixpushv1notify).", "properties": { "format": { "description": "The format in which to send notifications to the push gateway\nif the `kind` is `http`. The details about what fields the\nhomeserver should include are defined in the\n[Push Gateway Specification](https://spec.matrix.org/v1.19/push-gateway-api/). If omitted,\nthe server is expected to populate all of the event-related fields\nspecified in [`/_matrix/push/v1/notify`](https://spec.matrix.org/v1.19/push-gateway-api/#post_matrixpushv1notify).", "enum": [ "event_id_only" ], "type": "string" }, "url": { "description": "Required if `kind` is `http`. The URL to use for sending\nnotifications. MUST be an HTTPS URL with a path of\n`/_matrix/push/v1/notify`.", "example": "https://push-gateway.location.here/_matrix/push/v1/notify", "format": "uri", "type": "string" } }, "title": "PusherData", "type": "object" }, "device_display_name": { "description": "Required if `kind` is not `null`. A string that will allow the\nuser to identify what device owns this 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", "null" ] }, "lang": { "description": "Required if `kind` is not `null`. The preferred language for\nreceiving notifications (e.g. 'en' or '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", "pushkey" ], "type": "object" } } }, "description": "The pusher information.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "description": "An empty object.", "type": "object" } } }, "description": "The pusher was set." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "One or more of the pusher values were invalid." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Modify a pusher for this user on the homeserver.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushrules/": { "get": { "description": "Retrieve all push rulesets for this user. Currently the only push ruleset\ndefined is `global`.", "operationId": "getPushRules", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "global": { "allOf": [ { "example": { "override": [ { "actions": [], "conditions": [], "default": true, "enabled": false, "rule_id": ".m.rule.master" }, { "actions": [], "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": [ { "key": "content.m\\.mentions.user_ids", "kind": "event_property_contains", "value": "@alice:example.com" } ], "default": true, "enabled": true, "rule_id": ".m.rule.is_user_mention" }, { "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" } ] }, "properties": { "content": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "override": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "room": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "sender": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "underride": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" } }, "type": "object" } ], "description": "The global ruleset.", "title": "Ruleset", "type": "object" } }, "required": [ "global" ], "type": "object" } } }, "description": "All the push rulesets for this user." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve all push rulesets.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushrules/global/": { "get": { "description": "Retrieve all push rules for this user.", "operationId": "getPushRulesGlobal", "responses": { "200": { "content": { "application/json": { "schema": { "example": { "override": [ { "actions": [], "conditions": [], "default": true, "enabled": false, "rule_id": ".m.rule.master" }, { "actions": [], "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": [ { "key": "content.m\\.mentions.user_ids", "kind": "event_property_contains", "value": "@alice:example.com" } ], "default": true, "enabled": true, "rule_id": ".m.rule.is_user_mention" }, { "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" } ] }, "properties": { "content": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "override": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "room": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "sender": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" }, "underride": { "items": { "properties": { "actions": { "description": "The actions to perform when this rule is matched.", "items": { "type": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "type": "string" }, "rule_id": { "description": "The ID of this rule.", "type": "string" } }, "required": [ "actions", "default", "enabled", "rule_id" ], "title": "PushRule", "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "All the push rules for this user." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve all push rules.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushrules/global/{kind}/{ruleId}": { "delete": { "description": "This endpoint removes the push rule defined in the path.", "operationId": "deletePushRule", "parameters": [ { "description": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The push rule was deleted." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete a push rule.", "tags": [ "Push notifications" ] }, "get": { "description": "Retrieve a single specified push rule.", "operationId": "getPushRule", "parameters": [ { "description": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "actions": [], "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": [ "string", "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "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](https://spec.matrix.org/v1.19/appendices#glob-style-matching) to match against.\nOnly applicable to `content` rules.", "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" } } }, "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." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve a push rule.", "tags": [ "Push notifications" ] }, "put": { "description": "This endpoint allows the creation and modification of user defined push\nrules.\n\nIf a rule with the same `rule_id` already exists among rules of the same\nkind, it is updated with the new parameters, otherwise a new rule is\ncreated.\n\nIf both `after` and `before` are provided, the new or updated rule must\nbe the next most important rule with respect to the rule identified by\n`before`.\n\nIf neither `after` nor `before` are provided and the rule is created, it\nshould be added as the most important user defined rule among rules of\nthe same kind.\n\nWhen creating push rules, they MUST be enabled by default.", "operationId": "setPushRule", "parameters": [ { "description": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule. If the string starts with a dot (\".\"),\nthe request MUST be rejected as this is reserved for server-default\nrules. Slashes (\"/\") and backslashes (\"\\\\\") are also not allowed.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } }, { "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.", "example": "someRuleId", "in": "query", "name": "before", "required": false, "schema": { "type": "string" } }, { "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.", "example": "anotherRuleId", "in": "query", "name": "after", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "actions": [ "notify" ], "pattern": "cake*lie" }, "properties": { "actions": { "description": "The action(s) to perform when the conditions for this rule are met.", "items": { "type": [ "string", "object" ] }, "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": { "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`, `event_property_is` and `event_property_contains`\nconditions. The dot-separated field of the event 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`.", "example": "content.body", "type": "string" }, "kind": { "description": "The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.19/client-server-api/#conditions-1) for\nmore information on the allowed kinds and how they work.", "type": "string" }, "pattern": { "description": "Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.19/appendices#glob-style-matching)\nto match against.", "type": "string" }, "value": { "description": "Required for `event_property_is` and `event_property_contains` conditions.\nA non-compound [canonical JSON](https://spec.matrix.org/v1.19/appendices#canonical-json) value to match\nagainst.", "type": [ "string", "integer", "boolean", "null" ] } }, "required": [ "kind" ], "title": "PushCondition", "type": "object" }, "type": "array" }, "pattern": { "description": "Only applicable to `content` rules. The glob-style pattern to match against.", "type": "string" } }, "required": [ "actions" ], "type": "object" } } }, "description": "The push rule data. Additional top-level keys may be present depending\non the parameters for the rule `kind`.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The push rule was created/updated." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "There was a problem configuring this push rule." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist (when updating a push rule)." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Add or change a push rule.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushrules/global/{kind}/{ruleId}/actions": { "get": { "description": "This endpoint get the actions for the specified push rule.", "operationId": "getPushRuleActions", "parameters": [ { "description": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "actions": [ "notify", { "set_tweak": "sound", "value": "bing" } ] } } }, "schema": { "properties": { "actions": { "description": "The action(s) to perform for this rule.", "items": { "type": [ "string", "object" ] }, "type": "array" } }, "required": [ "actions" ], "type": "object" } } }, "description": "The actions for this push rule." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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": "The kind of rule\n", "example": "room", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "#spam:example.com", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "actions": [ "notify", { "set_tweak": "highlight" } ] }, "properties": { "actions": { "description": "The action(s) to perform for this rule.", "items": { "type": [ "string", "object" ] }, "type": "array" } }, "required": [ "actions" ], "type": "object" } } }, "description": "The action(s) to perform when the conditions for this rule are met.\n", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The actions for the push rule were set." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set the actions for a push rule.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/pushrules/global/{kind}/{ruleId}/enabled": { "get": { "description": "This endpoint gets whether the specified push rule is enabled.", "operationId": "isPushRuleEnabled", "parameters": [ { "description": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "enabled": true } } }, "schema": { "properties": { "enabled": { "description": "Whether the push rule is enabled or not.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } } }, "description": "Whether the push rule is enabled." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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": "The kind of rule\n", "example": "content", "in": "path", "name": "kind", "required": true, "schema": { "enum": [ "override", "underride", "sender", "room", "content" ], "type": "string" } }, { "description": "The identifier for the rule.\n", "example": "nocake", "in": "path", "name": "ruleId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "enabled": true }, "properties": { "enabled": { "description": "Whether the push rule is enabled or not.", "type": "boolean" } }, "required": [ "enabled" ], "type": "object" } } }, "description": "Whether the push rule is enabled or not.\n", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The push rule was enabled or disabled." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The push rule was 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" ], "title": "Error", "type": "object" } } }, "description": "The push rule does not exist." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Enable or disable a push rule.", "tags": [ "Push notifications" ] } }, "/_matrix/client/v3/refresh": { "post": { "description": "Refresh an access token. Clients should use the returned access token\nwhen making subsequent API calls, and store the returned refresh token\n(if given) in order to refresh the new access token when necessary.\n\nAfter an access token has been refreshed, a server can choose to\ninvalidate the old access token immediately, or can choose not to, for\nexample if the access token would expire soon anyways. Clients should\nnot make any assumptions about the old access token still being valid,\nand should use the newly provided access token instead.\n\nThe old refresh token remains valid until the new access token or refresh token\nis used, at which point the old refresh token is revoked.\n\nNote that this endpoint does not require authentication via an\naccess token. Authentication is provided via the refresh token.\n\nApplication Service identity assertion is disabled for this endpoint.", "operationId": "refresh", "requestBody": { "content": { "application/json": { "schema": { "example": { "refresh_token": "some_token" }, "properties": { "refresh_token": { "description": "The refresh token", "type": "string" } }, "required": [ "refresh_token" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "access_token": "a_new_token", "expires_in_ms": 60000, "refresh_token": "another_new_token" } } }, "schema": { "properties": { "access_token": { "description": "The new access token to use.", "type": "string" }, "expires_in_ms": { "description": "The lifetime of the access token, in milliseconds. If not\ngiven, the client can assume that the access token will not\nexpire.", "type": "integer" }, "refresh_token": { "description": "The new refresh token to use when the access token needs to\nbe refreshed again. If not given, the old refresh token can\nbe re-used.", "type": "string" } }, "required": [ "access_token" ], "type": "object" } } }, "description": "A new access token and refresh token were generated." }, "401": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_UNKNOWN_TOKEN", "error": "Soft logged out", "soft_logout": true } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The provided token was unknown, or has already been used." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "summary": "Refresh an access token", "x-addedInMatrixVersion": "1.3" } }, "/_matrix/client/v3/register": { "post": { "description": "This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.19/client-server-api/#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 authorise 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 any\n`username` which does 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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/appendices/#user-identifiers).\n\n**NOTE:** \n**[Added in `v1.17`]** \nEven if the server doesn't support the Legacy authentication API, it\nMUST support this endpoint for application services to be able to\n[create users](https://spec.matrix.org/v1.19/application-service-api/#server-admin-style-permissions).\n\nIn that case application services MUST set the `\"inhibit_login\": true`\nparameter as they cannot use it to log in as users. If the\n`inhibit_login` parameter is not set to `true`, the server MUST return a\n400 HTTP status code with an `M_APPSERVICE_LOGIN_UNSUPPORTED` error code.\n\n\n**WARNING:** \n**[Added in `v1.18`]** [OAuth 2.0 aware clients](https://spec.matrix.org/v1.19/client-server-api/#oauth-20-aware-clients)\nMUST NOT use this endpoint when the server offers the [`m.login.sso`\nauthentication flow](https://spec.matrix.org/v1.19/client-server-api/#client-login-via-sso) with\n`oauth_aware_preferred` set to `true`. Instead they MUST use the\n[`/login/sso/redirect`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3loginssoredirect)\nendpoint, adding the `action=register` parameter.\n", "operationId": "register", "parameters": [ { "description": "The kind of account to register. Defaults to `user`.", "example": "user", "in": "query", "name": "kind", "required": false, "schema": { "default": "user", "enum": [ "guest", "user" ], "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "auth": { "allOf": [ { "additionalProperties": { "description": "Keys dependent on the login type" }, "description": "Used by clients to submit authentication information to the 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 authentication type that the client is attempting to complete.\nMay be omitted if `session` is given, and the client is reissuing a\nrequest which it believes has been completed out-of-band (for example,\nvia the [fallback mechanism](https://spec.matrix.org/v1.19/client-server-api/#fallback)).", "type": "string" } }, "title": "Authentication Data", "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." }, "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" }, "refresh_token": { "description": "If `true`, the client supports refresh tokens.", "type": "boolean", "x-addedInMatrixVersion": "1.3" }, "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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 authorise 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" }, "expires_in_ms": { "description": "The lifetime of the access token, in milliseconds. Once\nthe access token has expired a new access token can be\nobtained by using the provided refresh token. If no\nrefresh token is provided, the client will need to re-log in\nto obtain a new access token. If not given, the client can\nassume that the access token will not expire.\n\nOmitted if the `inhibit_login` option is true.", "type": "integer", "x-addedInMatrixVersion": "1.3" }, "home_server": { "deprecated": true, "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.", "format": "mx-server-name", "type": "string" }, "refresh_token": { "description": "A refresh token for the account. This token can be used to\nobtain a new access token when it expires by calling the\n`/refresh` endpoint.\n\nOmitted if the `inhibit_login` option is true.", "type": "string", "x-addedInMatrixVersion": "1.3" }, "user_id": { "description": "The fully-qualified Matrix user ID (MXID) that has been registered.\n\nAny user ID returned by this API must conform to the grammar given in the\n[Matrix specification](https://spec.matrix.org/v1.19/appendices/#user-identifiers).", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "description": "The account has been registered." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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* **[Added in `v1.17`]** `M_APPSERVICE_LOGIN_UNSUPPORTED`: an application service\n used the `m.login.application_service` type without setting `inhibit_login` to `true`,\n but the server doesn't support logging in via the Legacy authentication API.\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." }, "401": { "content": { "application/json": { "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" ], "title": "Flow information", "type": "object" }, "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" } } }, "description": "The homeserver requires additional authentication information." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "summary": "Register for an account on this homeserver.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/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": [ { "description": "The username to check the availability of.", "example": "my_cool_localpart", "in": "query", "name": "username", "required": true, "schema": { "default": "my_cool_localpart", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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" } } }, "description": "The username is available" }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "summary": "Checks to see if a username is available on the server.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/register/email/requestToken": { "post": { "description": "The homeserver must check that the given email address is **not**\nalready associated with an account on this homeserver. The homeserver\nshould validate the email itself, either by sending a validation email\nitself or by using a service it has control over.", "operationId": "requestTokenToRegisterEmail", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "email": { "description": "The email address to validate.", "example": "alice@example.org", "format": "email", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "send_attempt": { "description": "The server will only send an email if the `send_attempt`\nis a number greater than the most recent one which it has seen,\nscoped to that `email` + `client_secret` pair. This is to\navoid repeatedly sending the same email in the case of request\nretries between the POSTing user and the identity server.\nThe client should increment this value if they desire a new\nemail (e.g. a reminder) to be sent. If they do not, the server\nshould respond with success but not resend the email.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "email", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An email has been sent to the specified address. Note that this\nmay be an email containing the validation token or it may be\ninforming the user of an error." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "Part of the request was invalid. This may include one of the following error codes:\n\n* `M_THREEPID_IN_USE` : The email address is already registered to an account on this server.\n However, if the homeserver has the ability to send email, it is recommended that the server\n instead send an email to the user with instructions on how to reset their password.\n This prevents malicious parties from being able to determine if a given email address\n has an account on the homeserver in question.\n* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server\n that is not trusted by this homeserver." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not permit the address to be bound." } }, "summary": "Begins the validation process for an email to be used during registration.", "tags": [ "Account management" ] } }, "/_matrix/client/v3/register/msisdn/requestToken": { "post": { "description": "The homeserver must check that the given phone number is **not**\nalready associated with an account on this homeserver. The homeserver\nshould validate the phone number itself, either by sending a validation\nmessage itself or by using a service it has control over.", "operationId": "requestTokenToRegisterMSISDN", "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "client_secret": { "description": "A unique string generated by the client, and used to identify the\nvalidation attempt. It must be a string consisting of the characters\n`[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it\nmust not be empty.\n", "example": "monkeys_are_GREAT", "type": "string" }, "country": { "description": "The two-letter uppercase ISO-3166-1 alpha-2 country code that the\nnumber in `phone_number` should be parsed as if it were dialled from.", "example": "GB", "type": "string" }, "next_link": { "description": "Optional. When the validation is completed, the identity server will\nredirect the user to this URL. This option is ignored when submitting\n3PID validation information through a POST request.", "example": "https://example.org/congratulations.html", "format": "uri", "type": "string" }, "phone_number": { "description": "The phone number to validate.", "example": "07700900001", "type": "string" }, "send_attempt": { "description": "The server will only send an SMS if the `send_attempt` is a\nnumber greater than the most recent one which it has seen,\nscoped to that `country` + `phone_number` + `client_secret`\ntriple. This is to avoid repeatedly sending the same SMS in\nthe case of request retries between the POSTing user and the\nidentity server. The client should increment this value if\nthey desire a new SMS (e.g. a reminder) to be sent.", "example": 1, "type": "integer" } }, "required": [ "client_secret", "country", "phone_number", "send_attempt" ], "type": "object" }, { "properties": { "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.\n\nRequired if an `id_server` is supplied.", "type": "string" }, "id_server": { "description": "The hostname of the identity server to communicate with. May optionally\ninclude a port. This parameter is ignored when the homeserver handles\n3PID verification.\n\nThis parameter is deprecated with a plan to be removed in a future specification\nversion for `/account/password` and `/register` requests.", "example": "id.example.com", "type": "string" } }, "type": "object" } ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "sid": { "description": "The session ID. Session IDs are opaque strings that must consist entirely\nof the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255\ncharacters and they must not be empty.", "example": "123abc", "type": "string" }, "submit_url": { "description": "An optional field containing a URL where the client must submit the\nvalidation token, with identical request and response parameters and error\ncodes to the Identity Service API's\n[`POST /validate/email/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validateemailsubmittoken)\nand [`POST /validate/msisdn/submitToken`](https://spec.matrix.org/v1.19/identity-service-api/#post_matrixidentityv2validatemsisdnsubmittoken)\nendpoints (without the requirement for an access token). The homeserver\nmust send this token to the user (if applicable), who should then be\nprompted to provide it to the client.\n\nIf this field is not present, the client can assume that verification\nwill happen without the client's involvement provided the homeserver\nadvertises a sufficiently recent version in the [`GET /versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions)\nresponse (ie: r0.5.0).", "example": "https://example.org/path/to/submitToken", "format": "uri", "type": "string", "x-changedInMatrixVersion": { "1.18": "The URL has the same request and response parameters and error codes as\nthe Identity Service API's endpoint." } } }, "required": [ "sid" ], "title": "RequestTokenResponse", "type": "object" } } }, "description": "An SMS message has been sent to the specified phone number. Note\nthat this may be an SMS message containing the validation token or\nit may be informing the user of an error." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "Part of the request was invalid. This may include one of the following error codes:\n\n* `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server.\n However, if the homeserver has the ability to send SMS message, it is recommended that the server\n instead send an SMS message to the user with instructions on how to reset their password.\n This prevents malicious parties from being able to determine if a given phone number\n has an account on the homeserver in question.\n* `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server\n that is not trusted by this homeserver." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_THREEPID_DENIED", "error": "Third-party identifier is not allowed" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The homeserver does not permit the address to be bound." } }, "summary": "Requests a validation token be sent to the given phone number for the purpose of registering an account", "tags": [ "Account management" ] } }, "/_matrix/client/v3/room_keys/keys": { "delete": { "description": "Delete the keys from the backup.", "operationId": "deleteRoomKeys", "parameters": [ { "description": "The backup from which to delete the key", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete the keys from the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "get": { "description": "Retrieve the keys from the backup.", "operationId": "getRoomKeys", "parameters": [ { "description": "The backup from which to retrieve the keys.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "rooms": { "description": "A map of room IDs to room key backup data.", "example": { "!room:example.org": { "sessions": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } } } }, "patternProperties": { "^!": { "allOf": [ { "description": "The backed up keys for a room.", "properties": { "sessions": { "additionalProperties": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" }, "description": "A map of session IDs to key data.", "example": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } }, "type": "object" } }, "required": [ "sessions" ], "title": "RoomKeyBackup", "type": "object" } ], "x-pattern-format": "mx-room-id" } }, "type": "object" } }, "required": [ "rooms" ], "type": "object" } } }, "description": "The key data. If no keys are found, then an object with an empty\n`rooms` property will be returned (`{\"rooms\": {}}`)." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve the keys from the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "put": { "description": "Store several keys in the backup.", "operationId": "putRoomKeys", "parameters": [ { "description": "The backup in which to store the keys. Must be the current backup.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "rooms": { "description": "A map of room IDs to room key backup data.", "example": { "!room:example.org": { "sessions": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } } } }, "patternProperties": { "^!": { "allOf": [ { "description": "The backed up keys for a room.", "properties": { "sessions": { "additionalProperties": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" }, "description": "A map of session IDs to key data.", "example": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } }, "type": "object" } }, "required": [ "sessions" ], "title": "RoomKeyBackup", "type": "object" } ], "x-pattern-format": "mx-room-id" } }, "type": "object" } }, "required": [ "rooms" ], "type": "object" } } }, "description": "The backup data.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded" }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "current_version": "42", "errcode": "M_WRONG_ROOM_KEYS_VERSION", "error": "Wrong backup 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" ], "title": "Error", "type": "object" } } }, "description": "The version specified does not match the current backup version.\nThe current version will be included in the `current_version`\nfield." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Store several keys in the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/room_keys/keys/{roomId}": { "delete": { "description": "Delete the keys from the backup for a given room.", "operationId": "deleteRoomKeysByRoomId", "parameters": [ { "description": "The backup from which to delete the key.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the specified key is for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete the keys from the backup for a given room.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "get": { "description": "Retrieve the keys from the backup for a given room.", "operationId": "getRoomKeysByRoomId", "parameters": [ { "description": "The backup from which to retrieve the key.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the requested key is for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The backed up keys for a room.", "properties": { "sessions": { "additionalProperties": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" }, "description": "A map of session IDs to key data.", "example": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } }, "type": "object" } }, "required": [ "sessions" ], "title": "RoomKeyBackup", "type": "object" } } }, "description": "The key data. If no keys are found, then an object with an empty\n`sessions` property will be returned (`{\"sessions\": {}}`)." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve the keys from the backup for a given room.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "put": { "description": "Store several keys in the backup for a given room.", "operationId": "putRoomKeysByRoomId", "parameters": [ { "description": "The backup in which to store the keys. Must be the current backup.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the keys are for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The backed up keys for a room.", "properties": { "sessions": { "additionalProperties": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" }, "description": "A map of session IDs to key data.", "example": { "sessionid1": { "first_message_index": 1, "forwarded_count": 0, "is_verified": true, "session_data": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" } } }, "type": "object" } }, "required": [ "sessions" ], "title": "RoomKeyBackup", "type": "object" } } }, "description": "The backup data", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded" }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "current_version": "42", "errcode": "M_WRONG_ROOM_KEYS_VERSION", "error": "Wrong backup 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" ], "title": "Error", "type": "object" } } }, "description": "The version specified does not match the current backup version.\nThe current version will be included in the `current_version`\nfield." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Store several keys in the backup for a given room.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/room_keys/keys/{roomId}/{sessionId}": { "delete": { "description": "Delete a key from the backup.", "operationId": "deleteRoomKeyBySessionId", "parameters": [ { "description": "The backup from which to delete the key", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the specified key is for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the megolm session whose key is to be deleted.", "example": "sessionid", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete a key from the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "get": { "description": "Retrieve a key from the backup.", "operationId": "getRoomKeyBySessionId", "parameters": [ { "description": "The backup from which to retrieve the key.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the requested key is for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the megolm session whose key is requested.", "example": "sessionid", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" } } }, "description": "The key data" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Key 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" ], "title": "Error", "type": "object" } } }, "description": "The key or backup was not found." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve a key from the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "put": { "description": "Store a key in the backup.", "operationId": "putRoomKeyBySessionId", "parameters": [ { "description": "The backup in which to store the key. Must be the current backup.", "example": "1", "in": "query", "name": "version", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room that the key is for.", "example": "!roomid:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the megolm session that the key is for.", "example": "sessionid", "in": "path", "name": "sessionId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "description": "The key data", "properties": { "first_message_index": { "description": "The index of the first message in the session that the key can decrypt.", "example": 1, "type": "integer" }, "forwarded_count": { "description": "The number of times this key has been forwarded via key-sharing between devices.", "example": 0, "type": "integer" }, "is_verified": { "description": "Whether the device backing up the key verified the device that the key\nis from.", "example": false, "type": "boolean" }, "session_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "ciphertext": "base64+ciphertext+of+JSON+data", "ephemeral": "base64+ephemeral+key", "mac": "base64+mac+of+ciphertext" }, "type": "object" } }, "required": [ "first_message_index", "forwarded_count", "is_verified", "session_data" ], "title": "KeyBackupData", "type": "object" } } }, "description": "The key data.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "count": { "description": "The number of keys stored in the backup", "example": 10, "type": "integer" }, "etag": { "description": "The new etag value representing stored keys in the backup.\n\nSee [`GET /room_keys/version/{version}`](client-server-api/#get_matrixclientv3room_keysversionversion)\nfor more details.", "example": "abcdefg", "type": "string" } }, "required": [ "etag", "count" ], "title": "RoomKeysUpdateResponse", "type": "object" } } }, "description": "The update succeeded." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "current_version": "42", "errcode": "M_WRONG_ROOM_KEYS_VERSION", "error": "Wrong backup 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" ], "title": "Error", "type": "object" } } }, "description": "The version specified does not match the current backup version.\nThe current version will be included in the `current_version`\nfield." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Store a key in the backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/room_keys/version": { "get": { "description": "Get information about the latest backup version.", "operationId": "getRoomKeysVersionCurrent", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "algorithm": { "description": "The algorithm used for storing backups.", "enum": [ "m.megolm_backup.v1.curve25519-aes-sha2" ], "example": "m.megolm_backup.v1.curve25519-aes-sha2", "type": "string" }, "auth_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "public_key": "abcdefg", "signatures": { "@alice:example.org": { "ed25519:deviceid": "signature" } } }, "type": "object" }, "count": { "description": "The number of keys stored in the backup.", "example": 42, "type": "integer" }, "etag": { "description": "An opaque string representing stored keys in the backup.\nClients can compare it with the `etag` value they received\nin the request of their last key storage request. If not\nequal, another client has modified the backup.", "example": "anopaquestring", "type": "string" }, "version": { "description": "The backup version.", "example": "1", "type": "string" } }, "required": [ "algorithm", "auth_data", "count", "etag", "version" ], "type": "object" } } }, "description": "The information about the backup." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "No current backup 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" ], "title": "Error", "type": "object" } } }, "description": "No backup exists." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get information about the latest backup version.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "post": { "description": "Creates a new backup.", "operationId": "postRoomKeysVersion", "requestBody": { "content": { "application/json": { "schema": { "properties": { "algorithm": { "description": "The algorithm used for storing backups.", "enum": [ "m.megolm_backup.v1.curve25519-aes-sha2" ], "example": "m.megolm_backup.v1.curve25519-aes-sha2", "type": "string" }, "auth_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "public_key": "abcdefg", "signatures": { "@alice:example.org": { "ed25519:deviceid": "signature" } } }, "type": "object" } }, "required": [ "algorithm", "auth_data" ], "type": "object" } } }, "description": "The backup configuration.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "version": { "description": "The backup version. This is an opaque string.", "example": "1", "type": "string" } }, "required": [ "version" ], "type": "object" } } }, "description": "The version id of the new backup." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Create a new backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/room_keys/version/{version}": { "delete": { "description": "Delete an existing key backup. Both the information about the backup,\nas well as all key data related to the backup will be deleted.", "operationId": "deleteRoomKeysVersion", "parameters": [ { "description": "The backup version to delete, as returned in the `version`\nparameter in the response of\n[`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3room_keysversion)\nor [`GET /_matrix/client/v3/room_keys/version/{version}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3room_keysversionversion).", "example": "1", "in": "path", "name": "version", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "The delete succeeded, or the specified backup was previously\ndeleted." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup specified does not exist. If the backup was previously\ndeleted, the call should succeed rather than returning an error." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Delete an existing key backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "get": { "description": "Get information about an existing backup.", "operationId": "getRoomKeysVersion", "parameters": [ { "description": "The backup version to get, as returned in the `version` parameter\nof the response in\n[`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3room_keysversion)\nor this endpoint.", "example": "1", "in": "path", "name": "version", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "algorithm": { "description": "The algorithm used for storing backups.", "enum": [ "m.megolm_backup.v1.curve25519-aes-sha2" ], "example": "m.megolm_backup.v1.curve25519-aes-sha2", "type": "string" }, "auth_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "public_key": "abcdefg", "signatures": { "@alice:example.org": { "ed25519:deviceid": "signature" } } }, "type": "object" }, "count": { "description": "The number of keys stored in the backup.", "example": 42, "type": "integer" }, "etag": { "description": "An opaque string representing stored keys in the backup.\nClients can compare it with the `etag` value they received\nin the request of their last key storage request. If not\nequal, another client has modified the backup.", "example": "anopaquestring", "type": "string" }, "version": { "description": "The backup version.", "example": "1", "type": "string" } }, "required": [ "algorithm", "auth_data", "count", "etag", "version" ], "type": "object" } } }, "description": "The information about the requested backup." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup specified does not exist." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get information about an existing backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" }, "put": { "description": "Update information about an existing backup. Only `auth_data` can be modified.", "operationId": "putRoomKeysVersion", "parameters": [ { "description": "The backup version to update, as returned in the `version`\nparameter in the response of\n[`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3room_keysversion)\nor [`GET /_matrix/client/v3/room_keys/version/{version}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3room_keysversionversion).", "example": "1", "in": "path", "name": "version", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "algorithm": { "description": "The algorithm used for storing backups. Must be the same as\nthe algorithm currently used by the backup.", "enum": [ "m.megolm_backup.v1.curve25519-aes-sha2" ], "example": "m.megolm_backup.v1.curve25519-aes-sha2", "type": "string" }, "auth_data": { "description": "Algorithm-dependent data. See the documentation for the backup\nalgorithms in [Server-side key backups](https://spec.matrix.org/v1.19/client-server-api/#server-side-key-backups) for more information on the\nexpected format of the data.", "example": { "public_key": "abcdefg", "signatures": { "@alice:example.org": { "ed25519:deviceid": "signature" } } }, "type": "object" }, "version": { "description": "The backup version. If present, must be the same as the\nversion in the path parameter.", "example": "1", "type": "string" } }, "required": [ "algorithm", "auth_data" ], "type": "object" } } }, "description": "The backup configuration", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The update succeeded." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "Algorithm does not match" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "A parameter was incorrect. For example, the `algorithm` does not\nmatch the current backup algorithm, or the `version` in the body\ndoes not match the `version` in the path." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown backup 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" ], "title": "Error", "type": "object" } } }, "description": "The backup specified does not exist." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Update information about an existing backup.", "tags": [ "End-to-end encryption" ], "x-addedInMatrixVersion": "1.1" } }, "/_matrix/client/v3/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:**\nClients are recommended not to display this list of aliases prominently\nas they are not curated, unlike those listed in the `m.room.canonical_alias`\nstate event.", "operationId": "getLocalAliases", "parameters": [ { "description": "The room ID to find local aliases of.", "example": "!abc123:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "format": "mx-room-alias", "pattern": "^#", "type": "string" }, "type": "array" } }, "required": [ "aliases" ], "type": "object" } } }, "description": "The list of local aliases for the room." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "Room alias invalid" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The given `roomAlias` is not a valid room alias." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The user is not permitted to retrieve the list of local aliases for the room." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get a list of local aliases on a given room.", "tags": [ "Room directory" ] } }, "/_matrix/client/v3/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.", "example": "!e42d8c:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "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`](https://spec.matrix.org/v1.19/client-server-api/#mroommember) event.", "type": "string", "x-addedInMatrixVersion": "1.1" }, "user_id": { "description": "The fully qualified user ID of the user being banned.", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been kicked and banned from the room." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Ban a user in the room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/rooms/{roomId}/context/{eventId}": { "get": { "description": "This API returns a number of events that happened just before and\nafter the specified event. This allows clients to get the context\nsurrounding an event.\n\n*Note*: This endpoint supports lazy-loading of room member events. See\n[Lazy-loading room members](https://spec.matrix.org/v1.19/client-server-api/#lazy-loading-room-members) for more information.", "operationId": "getEventContext", "parameters": [ { "description": "The room to get events from.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The event to get context around.", "example": "$f3h4d129462ha:example.com", "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } }, { "description": "The maximum number of context events to return. The limit applies\nto the sum of the `events_before` and `events_after` arrays. The\nrequested event ID is always returned in `event` even if `limit` is\n0. Defaults to 10.", "example": 3, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "A JSON `RoomEventFilter` to filter the returned events with. The\nfilter is only applied to `events_before`, `events_after`, and\n`state`. It is not applied to the `event` itself. The filter may\nbe applied before or/and after the `limit` parameter - whichever the\nhomeserver prefers.\n\nSee [Filtering](https://spec.matrix.org/v1.19/client-server-api/#filtering) for more information.", "example": "66696p746572", "in": "query", "name": "filter", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "end": "t29-57_2_0_2", "event": { "content": { "body": "filename.jpg", "info": { "h": 398, "is_animated": false, "mimetype": "image/jpeg", "size": 31037, "w": 394 }, "msgtype": "m.image", "url": "mxc://example.org/JWEIFJgwEIhweiWJE" }, "event_id": "$f3h4d129462ha:example.com", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } }, "events_after": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } } ], "events_before": [ { "content": { "body": "something-important.doc", "filename": "something-important.doc", "info": { "mimetype": "application/msword", "size": 46144 }, "msgtype": "m.file", "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe" }, "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, "membership": "join" } } ], "start": "t27-54_2_0_2", "state": [ { "content": { "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" }, "room_version": "11" }, "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, "membership": "join" } }, { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:example.com", "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } } ] } } }, "schema": { "description": "The events and state surrounding the requested event.", "properties": { "end": { "description": "A token that can be used to paginate forwards with using [`GET /messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages).", "type": "string" }, "event": { "allOf": [ { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } ], "description": "Details of the requested event." }, "events_after": { "description": "A list of room events that happened just after the\nrequested event, in chronological order.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "events_before": { "description": "A list of room events that happened just before the\nrequested event, in reverse-chronological order.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "start": { "description": "A token that can be used to paginate backwards with using [`GET /messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages).", "type": "string" }, "state": { "description": "The state of the room at the last event returned.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "The events and state surrounding the requested event." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get events and state around the specified event.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/rooms/{roomId}/event/{eventId}": { "get": { "description": "Get a single event based on `roomId/eventId`. You must have permission to\nretrieve this event e.g. by being a member in the room for this event.", "operationId": "getOneRoomEvent", "parameters": [ { "description": "The ID of the room the event is in.", "example": "!636q39766251:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The event ID to get.", "example": "$asfDuShaf7Gafaw:matrix.org", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "msgtype": "m.text" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:matrix.org", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } } }, "schema": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } } }, "description": "The full event." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Event 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" ], "title": "Error", "type": "object" } } }, "description": "The event was not found or you do not have permission to read this event." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get a single event by event ID.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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.", "example": "!au1ba7o:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The room has been forgotten." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The user has not left the room" }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Stop the requesting user remembering about a particular room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/rooms/{roomId}/initialSync": { "get": { "deprecated": false, "description": "Get a copy of the current state and the most recent messages in a room.\n\nThis endpoint should now exclusively be used for \"peeking\" into viewable rooms\nyou're not a member of ([Room Previews](https://spec.matrix.org/v1.19/client-server-api/#room-previews)).\nUsing this endpoint for something other than peeking was deprecated in r0 of this specification.\nThe relevant information for syncing is now returned by the\n[`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) API. See the\n[migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).", "operationId": "roomInitialSync", "parameters": [ { "description": "The room to get the data.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "account_data": [ { "content": { "tags": { "work": { "order": "1" } } }, "type": "m.tag" } ], "membership": "join", "messages": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } }, { "content": { "body": "something-important.doc", "filename": "something-important.doc", "info": { "mimetype": "application/msword", "size": 46144 }, "msgtype": "m.file", "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe" }, "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, "membership": "join" } } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!636q39766251:example.com", "state": [ { "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, "membership": "join" } }, { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:example.com", "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } }, { "content": { "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" }, "room_version": "11" }, "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, "membership": "join" } }, { "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, "membership": "join" } } ], "visibility": "private" } } }, "schema": { "properties": { "account_data": { "description": "The private data that this user has attached to this room.", "items": { "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" } ], "title": "Event", "type": "object" }, "type": "array" }, "membership": { "description": "The user's membership state in this room.", "enum": [ "invite", "join", "leave", "ban" ], "type": "string" }, "messages": { "description": "The pagination chunk for this room.", "properties": { "chunk": { "description": "If the user is a member of the room this will be a\nlist of the most recent messages for this room. If\nthe user has left the room this will be the\nmessages that preceded them leaving. This array\nwill consist of at most `limit` elements.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "end": { "description": "A token which correlates to the end of `chunk`. Can be passed to\n[`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages)\nto retrieve later events.", "type": "string" }, "start": { "description": "A token which correlates to the start of `chunk`. Can be passed to\n[`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages)\nto retrieve earlier events.\n\nIf no earlier events are available, this property may be omitted from\nthe response.", "type": "string" } }, "required": [ "end", "chunk" ], "title": "PaginationChunk", "type": "object" }, "room_id": { "description": "The ID of this room.", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "state": { "description": "If the user is a member of the room this will be the\ncurrent state of the room as a list of events. If the\nuser has left the room this will be the state of the\nroom when they left it.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "visibility": { "description": "Whether this room is visible to the `/publicRooms` API\nor not.", "enum": [ "private", "public" ], "type": "string" } }, "required": [ "room_id" ], "title": "RoomInfo", "type": "object" } } }, "description": "The current state of the room" }, "403": { "description": "You aren't a member of the room and weren't previously a member of the room.\n" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Snapshot the current state of a room and its most recent messages.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/rooms/{roomId}/invite": { "post": { "description": "*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](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3roomsroomidinvite).\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", "operationId": "inviteBy3PID", "parameters": [ { "description": "The room identifier (not alias) to which to invite the user.", "example": "!d41d8cd:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "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`\n(see [the list of recognised values](https://spec.matrix.org/v1.19/appendices/#3pid-types)).", "type": "string" } }, "required": [ "id_server", "id_access_token", "medium", "address" ], "title": "Invite3pid", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been invited to join the room." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to invite the user to the room. A\nmeaningful `errcode` and description error text will be returned.\nExample 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.\n\n**[Added in `v1.18`]** The `M_INVITE_BLOCKED` error code is used to\nindicate that the homeserver rejected the invite due to\n[invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission)." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Invite a user to participate in a particular room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/rooms/{roomId}/invite ": { "post": { "description": "*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](https://spec.matrix.org/v1.19/client-server-api/#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.", "operationId": "inviteUser", "parameters": [ { "description": "The room identifier (not alias) to which to invite the user.", "example": "!d41d8cd:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "Welcome to the team!", "user_id": "@cheeky_monkey:matrix.org" }, "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "type": "string", "x-addedInMatrixVersion": "1.1" }, "user_id": { "description": "The fully qualified user ID of the invitee.", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been invited to join the room, or was already invited to the room." }, "400": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to invite the user to the room. A\nmeaningful `errcode` and description error text will be returned.\nExample 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.\n\n**[Added in `v1.18`]** The `M_INVITE_BLOCKED` error code is used to\nindicate that the homeserver rejected the invite due to\n[invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission)." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Invite a user to participate in a particular room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/rooms/{roomId}/join": { "post": { "description": "*Note that this API requires a room ID, not alias.*\n`/join/{roomIdOrAlias}` *exists if you have a room alias.*\n\nThis API starts a user's participation 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`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3initialsync)\nand [`/sync`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync) APIs.", "operationId": "joinRoomById", "parameters": [ { "description": "The room identifier (not alias) to join.", "example": "!d41d8cd:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "example": "Looking for support", "type": "string", "x-addedInMatrixVersion": "1.1" }, "third_party_signed": { "allOf": [ { "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", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "sender": { "description": "The Matrix ID of the user who issued the invite.", "example": "@alice:example.org", "format": "mx-user-id", "pattern": "^@", "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" } ], "description": "If supplied, the homeserver must verify that it matches a pending\n`m.room.third_party_invite` event in the room, and perform\nkey validity checking if required by the event." } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "room_id": "!d41d8cd:matrix.org" } } }, "schema": { "properties": { "room_id": { "description": "The joined room ID.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } } }, "description": "The room has been joined.\n\nThe joined room ID must be returned in the `room_id` field." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to join the room. A meaningful `errcode`\nand 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.\n- The room is restricted and the user failed to satisfy any of the conditions." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Join the requesting user to a particular room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/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.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "joined": { "@bar:example.com": { "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK", "display_name": "Bar" } } } } }, "schema": { "properties": { "joined": { "description": "A map from user ID to a RoomMember object.", "patternProperties": { "^@": { "properties": { "avatar_url": { "description": "The avatar of the user this object is representing, as an [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris).", "format": "uri", "type": "string" }, "display_name": { "description": "The display name of the user this object is representing.", "type": "string" } }, "title": "RoomMember", "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "type": "object" } } }, "description": "A map of MXID to room member objects." }, "403": { "description": "You aren't a member of the room.\n" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets the list of currently joined users and their profile data.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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//state/m.room.member/`.", "operationId": "kick", "parameters": [ { "description": "The room identifier (not alias) from which the user should be kicked.", "example": "!e42d8c:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "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`](https://spec.matrix.org/v1.19/client-server-api/#mroommember) event.", "type": "string" }, "user_id": { "description": "The fully qualified user ID of the user being kicked.", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been kicked from the room." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "You do not have permission to kick the user from the room. A meaningful `errcode` and\ndescription 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." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Kick a user from the room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/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\nServers MAY additionally forget the room when this endpoint is called \u2013\njust as if the user had also invoked [`/forget`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3roomsroomidforget).\nServers that do this, MUST inform clients about this behavior using the\n[`m.forget_forced_upon_leave`](https://spec.matrix.org/v1.19/client-server-api/#mforget_forced_upon_leave-capability)\ncapability.\n\nIf the server doesn't automatically forget the room, the user will still be\nallowed to retrieve history from the room which they were previously allowed\nto see.", "operationId": "leaveRoom", "parameters": [ { "description": "The room identifier to leave.", "example": "!nkl290a:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "Saying farewell - thanks for the support!" }, "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "type": "string", "x-addedInMatrixVersion": "1.1" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The room has been left." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Stop the requesting user participating in a particular room.", "tags": [ "Room membership" ], "x-changedInMatrixVersion": { "1.18": "Servers may additionally forget the room provided that they make this behavior\ntransparent." } } }, "/_matrix/client/v3/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.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "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.", "example": "YWxsCgpOb25lLDM1ODcwOA", "in": "query", "name": "at", "schema": { "type": "string" } }, { "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`.", "example": "join", "in": "query", "name": "membership", "schema": { "enum": [ "join", "invite", "knock", "leave", "ban" ], "type": "string" } }, { "description": "The kind of membership to exclude from the results. Defaults to no\nfiltering if unspecified.", "example": "leave", "in": "query", "name": "not_membership", "schema": { "enum": [ "join", "invite", "knock", "leave", "ban" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:example.com", "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } } ] } } }, "schema": { "properties": { "chunk": { "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" } }, "type": "object" } } }, "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." }, "403": { "description": "You aren't a member of the room and weren't previously a member of the room.\n" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the m.room.member events for the room.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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](https://spec.matrix.org/v1.19/client-server-api/#lazy-loading-room-members) for more information.", "operationId": "getRoomEvents", "parameters": [ { "description": "The room to get events from.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The token to start returning events from. This token can be obtained\nfrom a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,\nor from an `end` token returned by a previous request to this endpoint.\n\nThis endpoint can also accept a value returned as a `start` token\nby a previous request to this endpoint, though servers are not\nrequired to support this. Clients should not rely on the behaviour.\n\nIf it is not provided, the homeserver shall return a list of messages\nfrom the first or last (per the value of the `dir` parameter) visible\nevent in the room history for the requesting user.", "example": "s345_678_333", "in": "query", "name": "from", "required": false, "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.3": "Previously, this field was required and paginating from the first or\nlast visible event in the room history wasn't supported.\n" } }, { "description": "The token to stop returning events at. This token can be obtained from\na `prev_batch` or `next_batch` token returned by the `/sync` endpoint,\nor from an `end` token returned by a previous request to this endpoint.", "in": "query", "name": "to", "required": false, "schema": { "type": "string" } }, { "description": "The direction to return events from. If this is set to `f`, events\nwill be returned in chronological order starting at `from`. If it\nis set to `b`, events will be returned in *reverse* chronological\norder, again starting at `from`.", "example": "b", "in": "query", "name": "dir", "required": true, "schema": { "enum": [ "b", "f" ], "type": "string" } }, { "description": "The maximum number of events to return. Default: 10.", "example": 3, "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "description": "A JSON RoomEventFilter to filter returned events with.", "example": "{\"contains_url\":true}", "in": "query", "name": "filter", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "chunk": [ { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "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, "membership": "join" } }, { "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, "membership": "join" } }, { "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, "membership": "join" } } ], "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. (The exact definition of `chronological`\nis dependent on the server implementation.)\n\nNote that an empty `chunk` does not *necessarily* imply that no more events\nare available. Clients should continue to paginate until no `end` property\nis returned.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" }, "end": { "description": "A token corresponding to the end of `chunk`. This token can be passed\nback to this endpoint to request further events.\n\nIf no further events are available (either because we have\nreached the start of the timeline, or because the user does\nnot have permission to see any more events), this property\nis omitted from the response.", "type": "string" }, "start": { "description": "A token corresponding to the start of `chunk`. This will be the same as\nthe value given 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": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "type": "array" } }, "required": [ "start", "chunk" ], "type": "object" } } }, "description": "A list of messages with a new token to request more." }, "403": { "description": "You aren't a member of the room.\n" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get a list of events for this room", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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.", "example": "!somewhere:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "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", "x-changedInMatrixVersion": { "1.4": "This property is no longer required.\n" } }, "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" }, "m.read.private": { "description": "The event ID to set the *private* read receipt location at. This\nequivalent to calling `/receipt/m.read.private/$elsewhere:example.org`\nand is provided here to save that extra call.", "example": "$elsewhere:example.org", "type": "string", "x-addedInMatrixVersion": "1.4" } }, "type": "object" } } }, "description": "The read marker and optional read receipt locations.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": {}, "type": "object" } } }, "description": "The read marker, and read receipt(s) if provided, have been updated." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set the position of the read marker for a room.", "tags": [ "Read Markers" ] } }, "/_matrix/client/v3/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.", "example": "!wefuh21ffskfuh345:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The type of receipt to send. This can also be `m.fully_read` as an\nalternative to [`/read_markers`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3roomsroomidread_markers).\n\nNote that `m.fully_read` does not appear under `m.receipt`: this endpoint\neffectively calls `/read_markers` internally when presented with a receipt\ntype of `m.fully_read`.", "example": "m.read", "in": "path", "name": "receiptType", "required": true, "schema": { "enum": [ "m.read", "m.read.private", "m.fully_read" ], "type": "string" }, "x-changedInMatrixVersion": { "1.4": "Allow `m.read.private` receipts and `m.fully_read` markers to be set.\n" } }, { "description": "The event ID to acknowledge up to.", "example": "$1924376522eioj:example.com", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "thread_id": "main" }, "properties": { "thread_id": { "description": "The [thread root](https://spec.matrix.org/v1.19/client-server-api/#threading)'s\n[event ID](https://spec.matrix.org/v1.19/appendices#event-ids) (or `main`) for which\nthread this receipt is intended to be under. If\nnot specified, the read receipt is *unthreaded*\n(default).", "type": "string", "x-addedInMatrixVersion": "1.4" } }, "type": "object" } } }, "description": "Extra receipt information to attach to `content` if any. The\nserver will automatically set the `ts` field.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "maxProperties": 0, "type": "object" } } }, "description": "The receipt was sent." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "thread_id field must be a non-empty string" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The `thread_id` is invalid in some way. For example:\n* It is not a string.\n* It is empty.\n* It is provided for an incompatible receipt type.\n* The `event_id` is not related to the `thread_id`." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Send a receipt for the given event ID.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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\nAny user with a power level greater than or equal to the `m.room.redaction`\nevent power level may send redactions for their own events in the room. If\nthe user's power level is also greater than or equal to the `redact` power\nlevel of the room, the user may redact events sent by other users.\n\nServer administrators may redact events sent by users on their server.", "operationId": "redactEvent", "parameters": [ { "description": "The room from which to redact the event.", "example": "!637q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The ID of the event to redact.", "example": "$bai2b1i9:matrix.org", "in": "path", "name": "eventId", "required": true, "schema": { "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, { "description": "The [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers) for this event. Clients should generate a\nunique ID; it will be used by the server to ensure idempotency of requests.", "example": "37", "in": "path", "name": "txnId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "Indecent material" }, "properties": { "reason": { "description": "The reason for the event being redacted.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "event_id": "$YUwQidLecu:example.com" } } }, "schema": { "properties": { "event_id": { "description": "A unique identifier for the event.", "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, "type": "object" } } }, "description": "An ID for the redaction event." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Strips all non-integrity-critical information out of an event.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/rooms/{roomId}/report": { "post": { "description": "Reports a room as inappropriate to the server, which may then notify\nthe appropriate people. How such information is delivered is left up to\nimplementations. The caller is not required to be joined to the room to\nreport it.\n\nClients could infer whether a reported room exists based on the 404 response.\nHomeservers that wish to conceal this information MAY return 200 responses\nregardless of the existence of the reported room.\n\nFurthermore, it might be possible for clients to deduce whether a reported\nroom exists by timing the response. This is because only a report for an\nexisting room will require the homeserver to do further processing. To\ncombat this, homeservers MAY add a random delay when generating a response.", "operationId": "reportRoom", "parameters": [ { "description": "The room being reported.", "example": "!637q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "this makes me sad" }, "properties": { "reason": { "description": "The reason the room is being reported. May be blank.", "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The room has been reported successfully." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The room was 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" ], "title": "Error", "type": "object" } } }, "description": "The room was not found on the homeserver." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Report a room as inappropriate.", "tags": [ "Reporting content" ], "x-addedInMatrixVersion": "1.13", "x-changedInMatrixVersion": { "1.18": "Servers MAY prevent room ID enumeration by using the 200 response\nregardless of the existence of the reported room and/or by adding\na random delay when generating responses.\n" } } }, "/_matrix/client/v3/rooms/{roomId}/report/{eventId}": { "post": { "description": "Reports an event as inappropriate to the server, which may then notify\nthe appropriate people. The caller must be joined to the room to report\nit.\n\nClients could infer whether a reported event or room exists based on the 404\nresponse. Homeservers that wish to conceal this information MAY return 200\nresponses regardless of the existence of the reported event or room.\n\nFurthermore, it might be possible for clients to deduce whether a reported\nevent exists by timing the response. This is because only a report for an\nexisting event will require the homeserver to do further processing. To\ncombat this, homeservers MAY add a random delay when generating a response.", "operationId": "reportEvent", "parameters": [ { "description": "The room in which the event being reported is located.", "example": "!637q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The event to report.", "example": "$something:example.org", "in": "path", "name": "eventId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "this makes me sad" }, "properties": { "reason": { "description": "The reason the content is being reported.", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The event has been reported successfully." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The event was not found or you are not joined to 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" ], "title": "Error", "type": "object" } } }, "description": "The event was not found or you are not joined to the room where the\nevent resides.\n\nHomeserver implementations can additionally return this error if the\nreported event has been redacted." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Report an event in a joined room as inappropriate.", "tags": [ "Reporting content" ], "x-changedInMatrixVersion": { "1.18": "The `score` request parameter was removed. Additionally, servers\nmay prevent event/room ID enumeration by using the 200 response\nregardless of the existence of the reported event/room.\n", "1.8": "This endpoint now requires the user to be joined to the room.\n" } } }, "/_matrix/client/v3/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](https://spec.matrix.org/v1.19/client-server-api/#room-events) for the `m.` event specification.\n\nHomeservers MUST allow clients to send `m.room.redaction` events with this\nendpoint for all room versions. In rooms with a version older than 11 they\nMUST move the `redacts` property inside the `content` to the top level of\nthe event.", "operationId": "sendMessage", "parameters": [ { "description": "The room to send the event to.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The type of event to send.", "example": "m.room.message", "in": "path", "name": "eventType", "required": true, "schema": { "type": "string" } }, { "description": "The [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers) 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.", "example": "35", "in": "path", "name": "txnId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "body": "hello", "msgtype": "m.text" }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "event_id": "$YUwRidLecu:example.com" } } }, "schema": { "properties": { "event_id": { "description": "A unique identifier for the event.", "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, "required": [ "event_id" ], "type": "object" } } }, "description": "An ID for the sent event." }, "400": { "content": { "application/json": { "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" ], "title": "Error", "type": "object" } } }, "description": "The request is invalid. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned. As well as the normal common error codes, other reasons for rejection include:\n\n- `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](https://spec.matrix.org/v1.19/client-server-api/#avoiding-duplicate-annotations)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Send a message event to the given room.", "tags": [ "Room participation" ], "x-changedInMatrixVersion": { "1.18": "Homeservers must support sending `m.room.redaction` events with this endpoint\nfor all room versions." } } }, "/_matrix/client/v3/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.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": [ { "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, "membership": "join" } }, { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "room_id": "!636q39766251:example.com", "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } }, { "content": { "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" }, "room_version": "11" }, "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, "membership": "join" } }, { "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, "membership": "join" } } ] } }, "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": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "title": "RoomState", "type": "array" } } }, "description": "The current state of the room" }, "403": { "description": "You aren't a member of the room and weren't previously a member of the room.\n" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get all state events in the current state of a room.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}": { "get": { "description": "Looks up the contents of a state event in a room. If the user is\njoined to the room then the state is taken from the current\nstate of the room. If the user has left the room then the state is\ntaken from the state of the room when they left.", "operationId": "getRoomStateWithKey", "parameters": [ { "description": "The room to look up the state in.", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The type of state to look up.", "example": "m.room.name", "in": "path", "name": "eventType", "required": true, "schema": { "type": "string" } }, { "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.", "example": "", "in": "path", "name": "stateKey", "required": true, "schema": { "type": "string" } }, { "description": "The format to use for the returned data. `content` (the default) will\nreturn only the content of the state event. `event` will return the entire\nevent in the usual format suitable for clients, including fields like event\nID, sender and timestamp.", "example": "event", "in": "query", "name": "format", "schema": { "enum": [ "content", "event" ], "type": "string" }, "x-addedInMatrixVersion": "1.16" } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "name": "Example room name" } } }, "schema": { "oneOf": [ { "type": "object" }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, { "properties": { "event_id": { "description": "The globally unique event identifier.", "format": "mx-event-id", "pattern": "^\\$", "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.", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "unsigned": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Contains optional extra information about the event.", "properties": { "age": { "description": "The time in milliseconds that has elapsed since the event was sent.", "type": "integer" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "sender", "origin_server_ts" ], "type": "object" } ], "description": "In addition to the Event fields, Room Events have the following additional fields.", "title": "SyncRoomEvent" }, { "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.", "format": "mx-room-id", "pattern": "^!", "type": "string" } }, "required": [ "room_id" ], "type": "object" } ], "description": "Room Events have the following fields.", "title": "RoomEvent" }, { "$schema": "https://json-schema.org/draft/2020-12/schema", "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "allOf": [ { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, { "properties": { "event_id": { "description": "The globally unique event identifier.", "format": "mx-event-id", "pattern": "^\\$", "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.", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "unsigned": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Contains optional extra information about the event.", "properties": { "age": { "description": "The time in milliseconds that has elapsed since the event was sent.", "type": "integer" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "sender", "origin_server_ts" ], "type": "object" } ], "description": "In addition to the Event fields, Room Events have the following additional fields.", "title": "SyncRoomEvent" }, { "properties": { "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" ], "type": "object" } ], "description": "In addition to the Room Event fields, State Events have the following additional fields.", "title": "SyncStateEvent" } ], "description": "State Events have the following fields.", "title": "StateEvent", "type": "object" } ] } } }, "description": "The content of the state event, or the entire client-formatted event\nif `?format=event` was used." }, "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": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the state identified by the type and key.", "tags": [ "Room participation" ] }, "put": { "description": "State events can be sent using this endpoint. These events will be\noverwritten if ``, `` and `` 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](https://spec.matrix.org/v1.19/client-server-api/#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", "example": "!636q39766251:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } }, { "description": "The type of event to send.", "example": "m.room.member", "in": "path", "name": "eventType", "required": true, "schema": { "type": "string" } }, { "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.", "example": "@alice:example.com", "in": "path", "name": "stateKey", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join" }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "event_id": "$YUwRidLecu:example.com" } } }, "schema": { "properties": { "event_id": { "description": "A unique identifier for the event.", "format": "mx-event-id", "pattern": "^\\$", "type": "string" } }, "required": [ "event_id" ], "type": "object" } } }, "description": "An ID for the sent event." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The sender's request is malformed.\n\nSome example error codes include:\n\n* `M_INVALID_PARAM`: 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." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The sender doesn't have permission to send the event into the room.\n\n**[Added in `v1.18`]** If the `eventType` is `m.room.member` and\nthe `membership` is `invite`, the `M_INVITE_BLOCKED` error code is\nused to indicate that the homeserver rejected the invite due to\n[invite blocking](https://spec.matrix.org/v1.19/client-server-api/#invite-permission)." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Send a state event to the given room.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "The room in which the user is typing.", "example": "!wefh3sfukhs:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "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" } } }, "description": "The current typing state.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The new typing state was set." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Informs the server that the user has started or stopped typing.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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.", "example": "!e42d8c:matrix.org", "in": "path", "name": "roomId", "required": true, "schema": { "format": "mx-room-id", "pattern": "^!", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "They've been banned long enough", "user_id": "@cheeky_monkey:matrix.org" }, "properties": { "reason": { "description": "Optional reason to be included as the `reason` on the subsequent\nmembership event.", "type": "string", "x-addedInMatrixVersion": "1.1" }, "user_id": { "description": "The fully qualified user ID of the user being unbanned.", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been unbanned from the room." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Unban a user from the room.", "tags": [ "Room membership" ] } }, "/_matrix/client/v3/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.", "example": "!oldroom:example.org", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "new_version": "2" }, "properties": { "additional_creators": { "description": "When upgrading to a [room version](https://spec.matrix.org/v1.19/rooms) which supports additional creators,\nthe [user IDs](https://spec.matrix.org/v1.19/appendices#user-identifiers) which should be considered room\ncreators in addition to the user performing the upgrade.\n\nIf the room being upgraded has additional creators, they are *not* automatically\ncopied to the new room. The full set of additional creators needs to be set to\nretain (or add/remove) more room creators.\n\nWhen upgrading to a room version which doesn't support additional creators, this\nfield is ignored and has no effect during the upgrade process.", "items": { "description": "Additional user ID to consider a room creator, if the room version supports it.", "type": "string" }, "type": "array", "x-addedInMatrixVersion": "1.16" }, "new_version": { "description": "The new version for the room.", "type": "string" } }, "required": [ "new_version" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "replacement_room": "!newroom:example.org" } } }, "schema": { "properties": { "replacement_room": { "description": "The ID of the new room.", "type": "string" } }, "required": [ "replacement_room" ], "type": "object" } } }, "description": "The room was successfully upgraded." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The request was invalid. One way this can happen is if the room version\nrequested is not supported by the homeserver." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The user is not permitted to upgrade the room." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upgrades a room to a new room version.", "tags": [ "Room upgrades" ] } }, "/_matrix/client/v3/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.", "example": "YWxsCgpOb25lLDM1ODcwOA", "in": "query", "name": "next_batch", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "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": [ { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "This takes a [filter](https://spec.matrix.org/v1.19/client-server-api/#filtering).", "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": "This is an example text message", "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, "membership": "join" } } } ] } } } } }, "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": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "Event", "type": "object" }, "title": "Events After", "type": "array" }, "events_before": { "description": "Events just before the result.", "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "Event", "type": "object" }, "title": "Events Before", "type": "array" }, "profile_info": { "description": "The historic profile information of the\nusers that sent the events returned.\n\nThe key is the user ID for which\nthe profile belongs to.", "patternProperties": { "^@": { "properties": { "avatar_url": { "format": "uri", "title": "Avatar Url", "type": "string" }, "displayname": { "title": "Display name", "type": "string" } }, "title": "User Profile", "type": "object", "x-pattern-format": "mx-user-id" } }, "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 format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" } ], "description": "The event that matched.", "title": "Event", "type": "object" } }, "title": "Result", "type": "object" }, "title": "Results", "type": "array" }, "state": { "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 key is the room ID for which the `State\nEvent` array belongs to.", "patternProperties": { "^!": { "items": { "allOf": [ { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, { "properties": { "room_id": { "description": "The ID of the room associated with this event.", "example": "!jEsUZKDJdhlrceRyVU:example.org", "format": "mx-room-id", "pattern": "^!", "type": "string" }, "unsigned": { "properties": { "redacted_because": { "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257 } }, "title": "ClientEvent" } } } }, "required": [ "room_id" ], "type": "object" } ], "description": "The format used for events when they are returned from a homeserver to a client\nvia the Client-Server API, or sent to an Application Service via the Application Services API.", "title": "ClientEvent", "type": "object" }, "title": "Room State", "type": "array", "x-pattern-format": "mx-room-id" } }, "title": "Current state", "type": "object" } }, "title": "Result Room Events", "type": "object" } }, "title": "Result Categories", "type": "object" } }, "required": [ "search_categories" ], "title": "Results", "type": "object" } } }, "description": "Results of the search." }, "400": { "description": "Part of the request was invalid." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Perform a server-side search.", "tags": [ "Search" ] } }, "/_matrix/client/v3/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.", "example": "m.new_device", "in": "path", "name": "eventType", "required": true, "schema": { "type": "string" } }, { "description": "The [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers) 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.", "example": "35", "in": "path", "name": "txnId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "messages": { "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" } } }, "patternProperties": { "^@": { "additionalProperties": { "description": "Message content", "title": "EventContent", "type": "object" }, "type": "object", "x-pattern-format": "mx-user-id" } }, "type": "object" } }, "required": [ "messages" ], "title": "body", "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The message was successfully sent." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Send an event to a given set of devices.", "tags": [ "Send-to-Device messaging" ] } }, "/_matrix/client/v3/sync": { "get": { "description": "Synchronise the client's state with the latest state on the server.\nClients use this API when they first log in to get an initial snapshot\nof the state on the server, and then continue to call this API to get\nincremental deltas to the state, and to receive new messages.\n\n*Note*: This endpoint supports lazy-loading. See [Filtering](https://spec.matrix.org/v1.19/client-server-api/#filtering)\nfor more information. Lazy-loading members is only supported on the `state` part of a\n[`RoomFilter`](#post_matrixclientv3useruseridfilter_request_roomfilter)\nfor this endpoint. When lazy-loading is enabled, servers MUST include the\nsyncing user's own membership event when they join a room, or when the\nfull state of rooms is requested, to aid discovering the user's avatar &\ndisplayname.\n\nFurther, like other members, the user's own membership event is eligible\nfor being considered redundant by the server. When a sync is `limited`,\nthe server MUST return membership events for events in the gap\n(between `since` and the start of the returned timeline), regardless\nas to whether or not they are redundant. This ensures that joins/leaves\nand profile changes which occur during the gap are not lost.\n\nNote that the default behaviour of `state` is to include all membership\nevents, alongside other state, when lazy-loading is not enabled.", "operationId": "sync", "parameters": [ { "description": "The ID of a filter created using the filter API or a filter JSON\nobject encoded as a string. The server will detect whether it is\nan ID or a JSON object by whether the first character is a `\"{\"`\nopen brace. Passing the JSON inline is best suited to one off\nrequests. Creating a filter using the filter API is recommended for\nclients that reuse the same filter multiple times, for example in\nlong poll requests.\n\nSee [Filtering](https://spec.matrix.org/v1.19/client-server-api/#filtering) for more information.", "example": "66696p746572", "in": "query", "name": "filter", "schema": { "type": "string" } }, { "description": "A point in time to continue a sync from. This should be the\n`next_batch` token returned by an earlier call to this endpoint.", "example": "s72594_4483_1934", "in": "query", "name": "since", "schema": { "type": "string" } }, { "description": "Controls whether to include the full state for all rooms the user\nis a member of.\n\nIf this is set to `true`, then all state events will be returned,\neven if `since` is non-empty. The timeline will still be limited\nby the `since` parameter. In this case, the `timeout` parameter\nwill be ignored and the query will return immediately, possibly with\nan empty timeline.\n\nIf `false`, and `since` is non-empty, only state which has\nchanged since the point indicated by `since` will be returned.\n\nBy default, this is `false`.", "example": false, "in": "query", "name": "full_state", "schema": { "type": "boolean" } }, { "description": "Controls whether the client is automatically marked as online by\npolling this API. If this parameter is omitted then the client is\nautomatically marked as online when it uses this API. Otherwise if\nthe parameter is set to \"offline\" then the client is not marked as\nbeing online when it uses this API. When set to \"unavailable\", the\nclient is marked as being idle.", "example": "offline", "in": "query", "name": "set_presence", "schema": { "enum": [ "offline", "online", "unavailable" ], "type": "string" } }, { "description": "The maximum time to wait, in milliseconds, before returning this\nrequest. If no events (or other data) become available before this\ntime elapses, the server will return a response with empty fields.\n\nBy default, this is `0`, so the server will return immediately\neven if the response is empty.", "example": 30000, "in": "query", "name": "timeout", "schema": { "type": "integer" } }, { "description": "Controls whether to receive state changes between the previous sync\nand the **start** of the timeline, or between the previous sync and\nthe **end** of the timeline.\n\nIf this is set to `true`, servers MUST respond with the state\nbetween the previous sync and the **end** of the timeline in\n`state_after` and MUST omit `state`.\n\nIf `false`, servers MUST respond with the state between the previous\nsync and the **start** of the timeline in `state` and MUST omit\n`state_after`.\n\nServers MAY implement this parameter ahead of declaring support for\nthe version of the spec in which it was introduced. Consequently,\nclients MAY set this parameter to `true` regardless of the\n[`/versions`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientversions) response.\nIf they do, they can infer whether the server actually supports this\nparameter from the presence of `state_after` in the response. If\n`state_after` is missing, clients MUST behave as if they had not\nspecified the parameter and update their local state with events\nin `state` and `timeline`.\n\nBy default, this is `false`.", "example": false, "in": "query", "name": "use_state_after", "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.16" } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "account_data": { "events": [ { "content": { "custom_config_key": "custom_config_value" }, "type": "org.example.custom.config" } ] }, "next_batch": "s72595_4483_1934", "presence": { "events": [ { "content": { "avatar_url": "mxc://localhost/wefuiwegh8742w", "currently_active": false, "last_active_ago": 2478593, "presence": "online", "status_msg": "Making cupcakes" }, "sender": "@example:localhost", "type": "m.presence" } ] }, "rooms": { "invite": { "!696r7674:example.com": { "invite_state": { "events": [ { "content": { "name": "My Room Name" }, "sender": "@alice:example.com", "state_key": "", "type": "m.room.name" }, { "content": { "membership": "invite" }, "sender": "@alice:example.com", "state_key": "@bob:example.com", "type": "m.room.member" } ] } } }, "join": { "!726s6s6q:example.com": { "account_data": { "events": [ { "content": { "tags": { "u.work": { "order": 0.9 } } }, "type": "m.tag" }, { "content": { "custom_config_key": "custom_config_value" }, "type": "org.example.custom.room.config" } ] }, "ephemeral": { "events": [ { "content": { "user_ids": [ "@alice:matrix.org", "@bob:example.com" ] }, "type": "m.typing" }, { "content": { "$1435641916114394fHBLK:matrix.org": { "m.read": { "@erikj:jki.re": { "ts": 1436451550453 } }, "m.read.private": { "@self:example.org": { "ts": 1661384801651 } } } }, "type": "m.receipt" } ] }, "state": { "events": [ { "content": { "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe", "displayname": "Example user", "membership": "join" }, "event_id": "$143273976499sgjks:example.org", "origin_server_ts": 1432735824653, "sender": "@example:example.org", "state_key": "@example:example.org", "type": "m.room.member", "unsigned": { "age": 45603, "membership": "join" } } ] }, "summary": { "m.heroes": [ "@alice:example.com", "@bob:example.com" ], "m.invited_member_count": 0, "m.joined_member_count": 2 }, "timeline": { "events": [ { "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join", "reason": "Looking for support" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "sender": "@alice:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234, "membership": "join" } }, { "content": { "body": "This is an example text message", "format": "org.matrix.custom.html", "formatted_body": "This is an example text message", "msgtype": "m.text" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts": 1432735824653, "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234, "membership": "join" } } ], "limited": true, "prev_batch": "t34-23535_0_0" }, "unread_notifications": { "highlight_count": 1, "notification_count": 5 }, "unread_thread_notifications": { "$threadroot": { "highlight_count": 3, "notification_count": 6 } } } }, "knock": { "!223asd456:example.com": { "knock_state": { "events": [ { "content": { "name": "My Room Name" }, "sender": "@alice:example.com", "state_key": "", "type": "m.room.name" }, { "content": { "membership": "knock" }, "sender": "@bob:example.com", "state_key": "@bob:example.com", "type": "m.room.member" } ] } } }, "leave": {} } } } }, "schema": { "properties": { "account_data": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" } }, "title": "EventBatch", "type": "object" } ], "description": "The global private data created by this user.", "title": "Account Data", "type": "object" }, "device_lists": { "description": "Information on end-to-end device updates, as specified in\n[End-to-end encryption](https://spec.matrix.org/v1.19/client-server-api/#e2e-extensions-to-sync).", "title": "DeviceLists", "type": "object" }, "device_one_time_keys_count": { "additionalProperties": { "type": "integer" }, "description": "Information on end-to-end encryption keys, as specified\nin [End-to-end encryption](https://spec.matrix.org/v1.19/client-server-api/#e2e-extensions-to-sync).", "title": "One-time keys count", "type": "object" }, "next_batch": { "description": "The batch token to supply in the `since` param of the next\n`/sync` request.", "type": "string" }, "presence": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" } }, "title": "EventBatch", "type": "object" } ], "description": "The updates to the presence status of other users.", "title": "Presence", "type": "object" }, "rooms": { "description": "Updates to rooms.", "properties": { "invite": { "description": "The rooms that the user has been invited to, mapped as room ID to\nroom information.", "patternProperties": { "^!": { "properties": { "invite_state": { "description": "The [stripped state](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) of a room that the user has\nbeen invited to.", "properties": { "events": { "description": "The [stripped state events](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) that form the\ninvite state.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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.", "format": "mx-user-id", "pattern": "^@", "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": "StrippedStateEvent", "type": "object" }, "type": "array" } }, "title": "InviteState", "type": "object" } }, "title": "Invited Room", "type": "object", "x-pattern-format": "mx-room-id" } }, "title": "Invited Rooms", "type": "object" }, "join": { "description": "The rooms that the user has joined, mapped as room ID to\nroom information.", "patternProperties": { "^!": { "properties": { "account_data": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" } }, "title": "EventBatch", "type": "object" } ], "description": "The private data that this user has attached to\nthis room.", "title": "Account Data", "type": "object" }, "ephemeral": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" } }, "title": "EventBatch", "type": "object" } ], "description": "The new ephemeral events in the room (events that\naren't recorded in the timeline or state of the\nroom). In this version of the spec, these are\n[typing notification](https://spec.matrix.org/v1.19/client-server-api/#typing-notifications)\nand [read receipt](https://spec.matrix.org/v1.19/client-server-api/#receipts) events.", "title": "Ephemeral", "type": "object" }, "state": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" } }, "title": "StateEventBatch", "type": "object" } ], "description": "Updates to the state, between the time indicated by\nthe `since` parameter, and the **start** of the\n`timeline` (or all state up to the **start** of the\n`timeline`, if `since` is not given, or\n`full_state` is true).\n\n**NOTE:** \nState updates for `m.room.member` events will\nbe incomplete if `lazy_load_members` is enabled in\nthe `/sync` filter, and only return the member events\nrequired to display the senders of the timeline events\nin this response.\n\n\nMUST be omitted if `use_state_after` was set to `true`\nin the request.", "title": "State", "type": "object" }, "state_after": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" } }, "title": "StateEventBatch", "type": "object" } ], "description": "Updates to the state, between the time indicated by\nthe `since` parameter, and the **end** of the\n`timeline` (or all state up to the **end** of the\n`timeline`, if `since` is not given, or\n`full_state` is true).\n\n**NOTE:** \nState updates for `m.room.member` events will\nbe incomplete if `lazy_load_members` is enabled in\nthe `/sync` filter, and only return the member events\nrequired to display the senders of the timeline events\nin this response.\n\n\nIf this field is set, even if it is empty, clients MUST\nonly update their local state with events in this list,\nand MUST NOT update their local state with events in\n`timeline`. If this field is not set, clients MUST update\ntheir local state with events in `state` and `timeline`.\n\n**Required** if `use_state_after` was set to `true` in the\nrequest, even if it is empty.", "title": "State", "type": "object", "x-addedInMatrixVersion": "1.16" }, "summary": { "description": "Information about the room which clients may need to\ncorrectly render it to users.", "properties": { "m.heroes": { "description": "The users which can be used to generate a room name\nif the room does not have one. Required if the room's\n`m.room.name` or `m.room.canonical_alias` state events\nare unset or empty.\n\nThis should be the first 5 members of the room, ordered\nby stream ordering, which are joined or invited. The\nlist must never include the client's own user ID. When\nno joined or invited members are available, this should\nconsist of the banned and left users. More than 5 members\nmay be provided, however less than 5 should only be provided\nwhen there are less than 5 members to represent.\n\nWhen lazy-loading room members is enabled, the membership\nevents for the heroes MUST be included in the `state`,\nunless they are redundant. When the list of users changes,\nthe server notifies the client by sending a fresh list of\nheroes. If there are no changes since the last sync, this\nfield may be omitted.", "items": { "format": "mx-user-id", "pattern": "^@", "type": "string" }, "type": "array" }, "m.invited_member_count": { "description": "The number of users with `membership` of `invite`.\nIf this field has not changed since the last sync, it\nmay be omitted. Required otherwise.", "type": "integer" }, "m.joined_member_count": { "description": "The number of users with `membership` of `join`,\nincluding the client's own user ID. If this field has\nnot changed since the last sync, it may be omitted.\nRequired otherwise.", "type": "integer" } }, "title": "RoomSummary", "type": "object" }, "timeline": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" }, "limited": { "description": "True if the number of events returned was limited by the `limit` on the filter.", "type": "boolean" }, "prev_batch": { "description": "A token that can be supplied to the `from` parameter of the [`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages) endpoint in order to retrieve earlier events.\nIf no earlier events are available, this property may be omitted from the response.", "type": "string" } }, "required": [ "events" ], "title": "TimelineBatch", "type": "object" } ], "description": "The timeline of messages and state changes in the\nroom.", "title": "Timeline", "type": "object" }, "unread_notifications": { "description": "Counts of unread notifications for this room. See the\n[Receiving notifications](https://spec.matrix.org/v1.19/client-server-api/#receiving-notifications) section\nfor more information on how these are calculated.\n\nIf `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,\nthese counts will only be for the main timeline rather than all events in the room.\nSee the [threading module](https://spec.matrix.org/v1.19/client-server-api/#threading) for more information.", "properties": { "highlight_count": { "description": "The number of unread notifications for this room with the highlight flag set.", "title": "Highlighted notification count", "type": "integer" }, "notification_count": { "description": "The total number of unread notifications for this room.", "title": "Total notification count", "type": "integer" } }, "title": "Unread Notification Counts", "type": "object", "x-changedInMatrixVersion": { "1.4": "Updated to reflect behaviour of having `unread_thread_notifications` as `true` in\nthe `RoomEventFilter` for `/sync`.\n" } }, "unread_thread_notifications": { "description": "If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,\nthe notification counts for each [thread](https://spec.matrix.org/v1.19/client-server-api/#threading) in this room.\nThe object is keyed by thread root ID, with values matching `unread_notifications`.\n\nIf a thread does not have any notifications it can be omitted from this object. If\nno threads have notification counts, this whole object can be omitted.", "patternProperties": { "^\\$": { "properties": { "highlight_count": { "description": "The number of unread notifications for this *thread* with the highlight flag set.", "title": "ThreadedHighlightNotificationCount", "type": "integer" }, "notification_count": { "description": "The total number of unread notifications for this *thread*.", "title": "ThreadedTotalNotificationCount", "type": "integer" } }, "title": "ThreadNotificationCounts", "type": "object", "x-pattern-format": "mx-event-id" } }, "title": "Unread Thread Notification Counts", "type": "object", "x-addedInMatrixVersion": "1.4" } }, "title": "Joined Room", "type": "object", "x-pattern-format": "mx-room-id" } }, "title": "Joined Rooms", "type": "object" }, "knock": { "description": "The rooms that the user has knocked upon, mapped as room ID to room information.", "patternProperties": { "^!": { "properties": { "knock_state": { "description": "The [stripped state](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) of a room that the user has\nknocked upon.", "properties": { "events": { "description": "The [stripped state events](https://spec.matrix.org/v1.19/client-server-api/#stripped-state) that form the\nknock state.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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.", "format": "mx-user-id", "pattern": "^@", "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": "StrippedStateEvent", "type": "object" }, "type": "array" } }, "title": "KnockState", "type": "object" } }, "title": "Knocked Room", "type": "object", "x-pattern-format": "mx-room-id" } }, "title": "Knocked rooms", "type": "object" }, "leave": { "description": "The rooms that the user has left or been banned from, mapped as room ID to\nroom information.", "patternProperties": { "^!": { "properties": { "account_data": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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, as defined by [the event type specification](https://spec.matrix.org/v1.19/client-server-api/#types-of-room-events).", "type": "string" } }, "required": [ "type", "content" ], "title": "Event", "type": "object" }, "type": "array" } }, "title": "EventBatch", "type": "object" } ], "description": "The private data that this user has attached to\nthis room.", "title": "Account Data", "type": "object" }, "state": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" } }, "title": "StateEventBatch", "type": "object" } ], "description": "The state updates for the room up to the **start** of the timeline.\n\nMUST be omitted if `use_state_after` was set to `true` in the\nrequest.", "title": "State", "type": "object" }, "state_after": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" } }, "title": "StateEventBatch", "type": "object" } ], "description": "The state updates for the room up to the **end** of the timeline.\n\nIf this field is set, even if it is empty, clients MUST only\nupdate their local state with events in this list, and MUST NOT\nupdate their local state with events in `timeline`. If this field\nis not set, clients MUST update their local state with events in\n`state` and `timeline`.\n\n**Required** if `use_state_after` was set to `true` in the\nrequest, even if it is empty.", "title": "State", "type": "object", "x-addedInMatrixVersion": "1.16" }, "timeline": { "allOf": [ { "properties": { "events": { "description": "List of events.", "items": { "description": "The format used for events when they are returned from\nAPI endpoints such as `/sync`, where the `room_id` is implied elsewhere\nin the response.", "properties": { "content": { "description": "The body of this event, as created by the client which sent it.", "example": { "membership": "join" }, "type": "object" }, "event_id": { "description": "The globally unique identifier for this event.", "example": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "format": "mx-event-id", "pattern": "^\\$", "type": "string" }, "origin_server_ts": { "description": "Timestamp (in milliseconds since the unix epoch) on originating homeserver\nwhen this event was sent.", "example": 1632489532305, "format": "int64", "type": "integer" }, "sender": { "description": "Contains the fully-qualified ID of the user who sent this event.", "example": "@example:example.org", "format": "mx-user-id", "pattern": "^@", "type": "string" }, "state_key": { "description": "Present if, and only if, this event is a *state* event. The key making\nthis piece of state unique in the room. Note that it is often an empty\nstring.\n\nState keys starting with an `@` are reserved for referencing user IDs, such\nas room members. With the exception of a few events, state events set with a\ngiven user's ID as the state key MUST only be set by that user.", "example": "@user:example.org", "type": "string" }, "type": { "description": "The type of the event.", "example": "m.room.member", "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.", "example": 1567437, "format": "int64", "type": "integer" }, "membership": { "description": "The room membership of the user making the request, at the time of the event.\n\nThis property is the value of the `membership` property of the\nrequesting user's [`m.room.member`](https://spec.matrix.org/v1.19/client-server-api#mroommember)\nstate at the point of the event, including any changes caused by the\nevent. If the user had yet to join the room at the time of the event\n(i.e, they have no `m.room.member` state), this property is set to\n`leave`.\n\nHomeservers SHOULD populate this property\nwherever practical, but they MAY omit it if necessary (for example,\nif calculating the value is expensive, servers might choose to only\nimplement it in encrypted rooms). The property is *not* normally populated\nin events pushed to application services via the application service transaction API\n(where there is no clear definition of \"requesting user\").\n", "example": "join", "type": "string", "x-addedInMatrixVersion": "1.11" }, "prev_content": { "description": "The `content` of the previous state event that was replaced by this event.\nThis field is generated by the local homeserver, and is only returned if\nthe event is a state event, and the client has permission to see the\nprevious event.\n", "title": "EventContent", "type": "object", "x-changedInMatrixVersion": { "1.2": "Previously, this field was specified at the top level of returned\nevents rather than in `unsigned` (with the exception of the [`GET\n.../notifications`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3notifications)\nendpoint), though in practice no known server implementations honoured\nthis.\n" } }, "redacted_because": { "description": "The event that redacted this event, if any.", "example": { "content": { "reason": "spam" }, "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE", "origin_server_ts": 1632491098485, "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45", "sender": "@moderator:example.org", "type": "m.room.redaction", "unsigned": { "age": 1257, "membership": "leave" } }, "title": "ClientEventWithoutRoomID", "type": "object" }, "replaces_state": { "description": "The event ID of the state event replaced by this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event.\nUnlike `prev_content`, this field is included regardless of history visibility.\n", "format": "mx-event-id", "pattern": "^\\$", "type": "string", "x-addedInMatrixVersion": "1.19" }, "transaction_id": { "description": "The client-supplied [transaction ID](https://spec.matrix.org/v1.19/client-server-api/#transaction-identifiers), for example, provided via\n`PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,\nif the client being given the event is the same one which sent it.\n", "type": "string" } }, "title": "UnsignedData", "type": "object" } }, "required": [ "event_id", "type", "sender", "origin_server_ts", "content" ], "title": "ClientEventWithoutRoomID", "type": "object" }, "type": "array" }, "limited": { "description": "True if the number of events returned was limited by the `limit` on the filter.", "type": "boolean" }, "prev_batch": { "description": "A token that can be supplied to the `from` parameter of the [`/rooms//messages`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3roomsroomidmessages) endpoint in order to retrieve earlier events.\nIf no earlier events are available, this property may be omitted from the response.", "type": "string" } }, "required": [ "events" ], "title": "TimelineBatch", "type": "object" } ], "description": "The timeline of messages and state changes in the\nroom up to the point when the user left.", "title": "Timeline", "type": "object" } }, "title": "Left Room", "type": "object", "x-pattern-format": "mx-room-id" } }, "title": "Left rooms", "type": "object" } }, "title": "Rooms", "type": "object" }, "to_device": { "description": "Information on the send-to-device messages for the client\ndevice, as defined in [Send-to-Device messaging](https://spec.matrix.org/v1.19/client-server-api/#extensions-to-sync).", "title": "ToDevice", "type": "object" } }, "required": [ "next_batch" ], "type": "object" } } }, "description": "The initial snapshot or delta for the client to use to update their state." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Synchronise the client's state and receive new messages.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/thirdparty/location": { "get": { "description": "Retrieve an array of third-party network locations from a Matrix room\nalias.", "operationId": "queryLocationByAlias", "parameters": [ { "description": "The Matrix room alias to look up.", "example": "#matrix:matrix.org", "in": "query", "name": "alias", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "List of matched third-party locations.", "items": { "properties": { "alias": { "description": "An alias for a matrix room.", "example": "#freenode_#matrix:matrix.org", "type": "string" }, "fields": { "description": "Information used to identify this third-party location.", "example": { "channel": "#matrix", "network": "freenode" }, "type": "object" }, "protocol": { "description": "The protocol ID that the third-party location is a part of.", "example": "irc", "type": "string" } }, "required": [ "alias", "protocol", "fields" ], "title": "Location", "type": "object" }, "type": "array" } } }, "description": "All found third-party locations." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_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" ], "title": "Error", "type": "object" } } }, "description": "The Matrix room alias was not found" } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Reverse-lookup third-party locations given a Matrix room alias.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/thirdparty/location/{protocol}": { "get": { "description": "Requesting this endpoint with a valid protocol name results in a list\nof successful mapping results in a JSON array. Each result contains\nobjects to represent the Matrix room or rooms that represent a portal\nto this third-party network. Each has the Matrix room alias string,\nan identifier for the particular third-party network protocol, and an\nobject containing the network-specific fields that comprise this\nidentifier. It should attempt to canonicalise the identifier as much\nas reasonably possible given the network type.", "operationId": "queryLocationByProtocol", "parameters": [ { "description": "The protocol used to communicate to the third-party network.", "example": "irc", "in": "path", "name": "protocol", "required": true, "schema": { "type": "string" } }, { "description": "One or more custom fields to help identify the third-party\nlocation.", "in": "query", "name": "fields", "schema": { "additionalProperties": { "type": "string" }, "type": "object" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "List of matched third-party locations.", "items": { "properties": { "alias": { "description": "An alias for a matrix room.", "example": "#freenode_#matrix:matrix.org", "type": "string" }, "fields": { "description": "Information used to identify this third-party location.", "example": { "channel": "#matrix", "network": "freenode" }, "type": "object" }, "protocol": { "description": "The protocol ID that the third-party location is a part of.", "example": "irc", "type": "string" } }, "required": [ "alias", "protocol", "fields" ], "title": "Location", "type": "object" }, "type": "array" } } }, "description": "At least one portal room was found." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_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" ], "title": "Error", "type": "object" } } }, "description": "No portal rooms were found." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve Matrix-side portals rooms leading to a third-party location.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/thirdparty/protocol/{protocol}": { "get": { "description": "Fetches the metadata from the homeserver about a particular third-party protocol.", "operationId": "getProtocolMetadata", "parameters": [ { "description": "The name of the protocol.", "example": "irc", "in": "path", "name": "protocol", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "field_types": { "additionalProperties": { "description": "Definition of valid values for a field.", "properties": { "placeholder": { "description": "A placeholder serving as a valid example of the field value.", "type": "string" }, "regexp": { "description": "A regular expression for validation of a field's value. This may be relatively\ncoarse to verify the value as the application service providing this protocol\nmay apply additional validation or filtering.", "type": "string" } }, "required": [ "regexp", "placeholder" ], "title": "Field Type", "type": "object" }, "description": "The type definitions for the fields defined in `user_fields` and\n`location_fields`. Each entry in those arrays MUST have an entry here.\nThe `string` key for this object is the field name itself.\n\nMay be an empty object if no fields are defined.", "example": { "channel": { "placeholder": "#foobar", "regexp": "#[^\\s]+" }, "network": { "placeholder": "irc.example.org", "regexp": "([a-z0-9]+\\.)*[a-z0-9]+" }, "nickname": { "placeholder": "username", "regexp": "[^\\s#]+" } }, "type": "object" }, "icon": { "description": "A content URI representing an icon for the third-party protocol.", "example": "mxc://example.org/aBcDeFgH", "type": "string" }, "location_fields": { "description": "Fields which may be used to identify a third-party location. These should be\nordered to suggest the way that entities may be grouped, where higher\ngroupings are ordered first. For example, the name of a network should be\nsearched before the name of a channel.", "example": [ "network", "channel" ], "items": { "description": "Field used to identify a third-party location.", "type": "string" }, "type": "array" }, "user_fields": { "description": "Fields which may be used to identify a third-party user. These should be\nordered to suggest the way that entities may be grouped, where higher\ngroupings are ordered first. For example, the name of a network should be\nsearched before the nickname of a user.", "example": [ "network", "nickname" ], "items": { "description": "Field used to identify a third-party user.", "type": "string" }, "type": "array" } }, "required": [ "user_fields", "location_fields", "icon", "field_types" ], "title": "Protocol", "type": "object" }, { "properties": { "instances": { "description": "A list of objects representing independent instances of configuration.\nFor example, multiple networks on IRC if multiple are provided by the\nsame application service.\n\nThe instances are modified by the homeserver from the response of\n[`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](https://spec.matrix.org/v1.19/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)\nto include an `instance_id` to serve as a unique identifier for each\ninstance on the homeserver.", "items": { "allOf": [ { "properties": { "desc": { "description": "A human-readable description for the protocol, such as the name.", "example": "Freenode", "type": "string" }, "fields": { "description": "Preset values for `fields` the client may use to search by.", "example": { "network": "freenode" }, "type": "object" }, "icon": { "description": "An optional content URI representing the protocol. Overrides the one provided\nat the higher level Protocol object.", "example": "mxc://example.org/JkLmNoPq", "type": "string" }, "network_id": { "description": "A unique identifier across all instances.", "example": "freenode", "type": "string" } }, "required": [ "desc", "fields", "network_id" ], "title": "Protocol Instance", "type": "object" }, { "properties": { "instance_id": { "description": "A unique identifier for this instance on the homeserver. This field is added\nto the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](https://spec.matrix.org/v1.19/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)\nby the homeserver.\n\nThis is the identifier to use as the `third_party_instance_id` in a request to\n[`POST /_matrix/client/v3/publicRooms`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3publicrooms).", "example": "irc-freenode", "type": "string" } }, "type": "object" } ] }, "type": "array" } }, "required": [ "instances" ], "type": "object" } ] } } }, "description": "The protocol was found and metadata returned." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_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" ], "title": "Error", "type": "object" } } }, "description": "The protocol is unknown." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve metadata about a specific protocol that the homeserver supports.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/thirdparty/protocols": { "get": { "description": "Fetches the overall metadata about protocols supported by the\nhomeserver. Includes both the available protocols and all fields\nrequired for queries against each protocol.", "operationId": "getProtocols", "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": { "allOf": [ { "properties": { "field_types": { "additionalProperties": { "description": "Definition of valid values for a field.", "properties": { "placeholder": { "description": "A placeholder serving as a valid example of the field value.", "type": "string" }, "regexp": { "description": "A regular expression for validation of a field's value. This may be relatively\ncoarse to verify the value as the application service providing this protocol\nmay apply additional validation or filtering.", "type": "string" } }, "required": [ "regexp", "placeholder" ], "title": "Field Type", "type": "object" }, "description": "The type definitions for the fields defined in `user_fields` and\n`location_fields`. Each entry in those arrays MUST have an entry here.\nThe `string` key for this object is the field name itself.\n\nMay be an empty object if no fields are defined.", "example": { "channel": { "placeholder": "#foobar", "regexp": "#[^\\s]+" }, "network": { "placeholder": "irc.example.org", "regexp": "([a-z0-9]+\\.)*[a-z0-9]+" }, "nickname": { "placeholder": "username", "regexp": "[^\\s#]+" } }, "type": "object" }, "icon": { "description": "A content URI representing an icon for the third-party protocol.", "example": "mxc://example.org/aBcDeFgH", "type": "string" }, "location_fields": { "description": "Fields which may be used to identify a third-party location. These should be\nordered to suggest the way that entities may be grouped, where higher\ngroupings are ordered first. For example, the name of a network should be\nsearched before the name of a channel.", "example": [ "network", "channel" ], "items": { "description": "Field used to identify a third-party location.", "type": "string" }, "type": "array" }, "user_fields": { "description": "Fields which may be used to identify a third-party user. These should be\nordered to suggest the way that entities may be grouped, where higher\ngroupings are ordered first. For example, the name of a network should be\nsearched before the nickname of a user.", "example": [ "network", "nickname" ], "items": { "description": "Field used to identify a third-party user.", "type": "string" }, "type": "array" } }, "required": [ "user_fields", "location_fields", "icon", "field_types" ], "title": "Protocol", "type": "object" }, { "properties": { "instances": { "description": "A list of objects representing independent instances of configuration.\nFor example, multiple networks on IRC if multiple are provided by the\nsame application service.\n\nThe instances are modified by the homeserver from the response of\n[`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](https://spec.matrix.org/v1.19/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)\nto include an `instance_id` to serve as a unique identifier for each\ninstance on the homeserver.", "items": { "allOf": [ { "properties": { "desc": { "description": "A human-readable description for the protocol, such as the name.", "example": "Freenode", "type": "string" }, "fields": { "description": "Preset values for `fields` the client may use to search by.", "example": { "network": "freenode" }, "type": "object" }, "icon": { "description": "An optional content URI representing the protocol. Overrides the one provided\nat the higher level Protocol object.", "example": "mxc://example.org/JkLmNoPq", "type": "string" }, "network_id": { "description": "A unique identifier across all instances.", "example": "freenode", "type": "string" } }, "required": [ "desc", "fields", "network_id" ], "title": "Protocol Instance", "type": "object" }, { "properties": { "instance_id": { "description": "A unique identifier for this instance on the homeserver. This field is added\nto the response of [`GET /_matrix/app/v1/thirdparty/protocol/{protocol}`](https://spec.matrix.org/v1.19/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol)\nby the homeserver.\n\nThis is the identifier to use as the `third_party_instance_id` in a request to\n[`POST /_matrix/client/v3/publicRooms`](https://spec.matrix.org/v1.19/client-server-api/#post_matrixclientv3publicrooms).", "example": "irc-freenode", "type": "string" } }, "type": "object" } ] }, "type": "array" } }, "required": [ "instances" ], "type": "object" } ] }, "description": "Dictionary of supported third-party protocols.", "example": { "gitter": { "field_types": { "room": { "placeholder": "matrix-org/matrix-spec", "regexp": "[^\\s]+\\/[^\\s]+" }, "username": { "placeholder": "@username", "regexp": "@[^\\s]+" } }, "instances": [ { "desc": "Gitter", "fields": {}, "icon": "mxc://example.org/zXyWvUt", "instance_id": "gitter-gitter", "network_id": "gitter" } ], "location_fields": [ "room" ], "user_fields": [ "username" ] }, "irc": { "field_types": { "channel": { "placeholder": "#foobar", "regexp": "#[^\\s]+" }, "network": { "placeholder": "irc.example.org", "regexp": "([a-z0-9]+\\.)*[a-z0-9]+" }, "nickname": { "placeholder": "username", "regexp": "[^\\s]+" } }, "icon": "mxc://example.org/aBcDeFgH", "instances": [ { "desc": "Freenode", "fields": { "network": "freenode.net" }, "icon": "mxc://example.org/JkLmNoPq", "instance_id": "irc-freenode", "network_id": "freenode" } ], "location_fields": [ "network", "channel" ], "user_fields": [ "network", "nickname" ] } }, "type": "object" } } }, "description": "The protocols supported by the homeserver." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve metadata about all protocols that a homeserver supports.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/thirdparty/user": { "get": { "description": "Retrieve an array of third-party users from a Matrix User ID.", "operationId": "queryUserByID", "parameters": [ { "description": "The Matrix User ID to look up.", "example": "@bob:matrix.org", "in": "query", "name": "userid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "List of matched third-party users.", "items": { "properties": { "fields": { "description": "Information used to identify this third-party location.", "example": { "user": "jim" }, "type": "object" }, "protocol": { "description": "The protocol ID that the third-party location is a part of.", "example": "gitter", "type": "string" }, "userid": { "description": "A Matrix User ID representing a third-party user.", "example": "@_gitter_jim:matrix.org", "type": "string" } }, "required": [ "userid", "protocol", "fields" ], "title": "User", "type": "object" }, "type": "array" } } }, "description": "An array of third-party users." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_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" ], "title": "Error", "type": "object" } } }, "description": "The Matrix User ID was not found." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Reverse-lookup third-party users given a Matrix User ID.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/thirdparty/user/{protocol}": { "get": { "description": "Retrieve a Matrix User ID linked to a user on the third-party service, given\na set of user parameters.", "operationId": "queryUserByProtocol", "parameters": [ { "description": "The name of the protocol.", "example": "irc", "in": "path", "name": "protocol", "required": true, "schema": { "type": "string" } }, { "description": "One or more custom fields that are passed to the AS to help identify the user.", "in": "query", "name": "fields", "schema": { "additionalProperties": { "type": "string" }, "type": "object" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "description": "List of matched third-party users.", "items": { "properties": { "fields": { "description": "Information used to identify this third-party location.", "example": { "user": "jim" }, "type": "object" }, "protocol": { "description": "The protocol ID that the third-party location is a part of.", "example": "gitter", "type": "string" }, "userid": { "description": "A Matrix User ID representing a third-party user.", "example": "@_gitter_jim:matrix.org", "type": "string" } }, "required": [ "userid", "protocol", "fields" ], "title": "User", "type": "object" }, "type": "array" } } }, "description": "The Matrix User IDs found with the given parameters." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_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" ], "title": "Error", "type": "object" } } }, "description": "The Matrix User ID was not found." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Retrieve the Matrix User ID of a corresponding third-party user.", "tags": [ "Third-party Lookup" ] } }, "/_matrix/client/v3/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\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The event type of the account data to get. Custom types should be\nnamespaced to avoid clashes.", "example": "org.example.custom.config", "in": "path", "name": "type", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "custom_account_data_key": "custom_config_value" }, "type": "object" } } }, "description": "The account data content for the given type." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Cannot add account data for other users." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The access token provided is not authorised to retrieve this user's account \ndata. Errcode: `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Account data 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" ], "title": "Error", "type": "object" } } }, "description": "No account data has been provided for this user with the given `type`.\nErrcode: `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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 available to clients through the\ntop-level `account_data` field in the homeserver response to\n[/sync](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync).", "operationId": "setAccountData", "parameters": [ { "description": "The ID of the user to set account data for. The access token must be\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The event type of the account data to set. Custom types should be\nnamespaced to avoid clashes.", "example": "org.example.custom.config", "in": "path", "name": "type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "custom_account_data_key": "custom_config_value" }, "type": "object" } } }, "description": "The content of the account data.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The account data was successfully added." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_JSON", "error": "Content must be a JSON object." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The request body is not a JSON object. Errcode: `M_BAD_JSON`\nor `M_NOT_JSON`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Cannot add account data for other users." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The access token provided is not authorised to modify this user's account \ndata. Errcode: `M_FORBIDDEN`." }, "405": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_BAD_JSON", "error": "Cannot set m.fully_read through this API." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "This `type` of account data is controlled by the server; it cannot be\nmodified by clients. Errcode: `M_BAD_JSON`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set some account data for the user.", "tags": [ "User data" ] } }, "/_matrix/client/v3/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 authorised to make requests for this user id.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "properties": { "account_data": { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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 are [dot-separated paths for each property](https://spec.matrix.org/v1.19/appendices#dot-separated-property-paths) to include. So `['content.body']` will include the `body` field of the `content` object. 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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "The ephemeral events to include for rooms. These are the events that appear in the `ephemeral` property in the `/sync` response." }, "include_leave": { "description": "Include rooms that the user has left in the sync. 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. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data`", "items": { "format": "mx-room-id", "pattern": "^!", "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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "state": { "allOf": [ { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "The state events to include for rooms.", "type": "object" }, "timeline": { "allOf": [ { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "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" } } }, "description": "The filter to upload.", "required": true }, "responses": { "200": { "content": { "application/json": { "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" } } }, "description": "The filter was created." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload a new filter.", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/user/{userId}/filter/{filterId}": { "get": { "operationId": "getFilter", "parameters": [ { "description": "The user ID to download a filter for.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } }, { "description": "The filter ID to download.", "example": "66696p746572", "in": "path", "name": "filterId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "properties": { "account_data": { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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 are [dot-separated paths for each property](https://spec.matrix.org/v1.19/appendices#dot-separated-property-paths) to include. So `['content.body']` will include the `body` field of the `content` object. 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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "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, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "The ephemeral events to include for rooms. These are the events that appear in the `ephemeral` property in the `/sync` response." }, "include_leave": { "description": "Include rooms that the user has left in the sync. 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. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data`", "items": { "format": "mx-room-id", "pattern": "^!", "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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "state": { "allOf": [ { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "The state events to include for rooms.", "type": "object" }, "timeline": { "allOf": [ { "allOf": [ { "properties": { "limit": { "description": "The maximum number of events to return, must be an integer greater than 0.\n\nServers should apply a default value, and impose a maximum value to avoid\nresource exhaustion.\n", "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": { "format": "mx-user-id", "pattern": "^@", "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": { "format": "mx-user-id", "pattern": "^@", "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](https://spec.matrix.org/v1.19/client-server-api/#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](https://spec.matrix.org/v1.19/client-server-api/#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": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "rooms": { "description": "A list of room IDs to include. If this list is absent then all rooms are included.", "items": { "format": "mx-room-id", "pattern": "^!", "type": "string" }, "type": "array" }, "unread_thread_notifications": { "description": "If `true`, enables per-[thread](https://spec.matrix.org/v1.19/client-server-api/#threading) notification\ncounts. Only applies to the `/sync` endpoint. Defaults to `false`.", "type": "boolean", "x-addedInMatrixVersion": "1.4" } }, "title": "RoomEventFilter", "type": "object" } ] } ], "description": "The message and state update events to include for rooms." } }, "title": "RoomFilter", "type": "object" } }, "title": "Filter", "type": "object" } } }, "description": "The filter definition." }, "404": { "description": "Unknown filter." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Download a filter", "tags": [ "Room participation" ] } }, "/_matrix/client/v3/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 an OpenID token for. Should be the user who\nis authenticated for the request.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": {}, "type": "object" } } }, "description": "An empty object. Reserved for future expansion.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "OpenIdCredentials", "type": "object" } } }, "description": "OpenID token information. This response is nearly compatible with the\nresponse documented in the\n[OpenID Connect 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." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get an OpenID token object to verify the requester's identity.", "tags": [ "OpenID" ] } }, "/_matrix/client/v3/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 get account data for. The access token must be\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room to get account data for.", "example": "!726s6s6q:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The event type of the account data to get. Custom types should be\nnamespaced to avoid clashes.", "example": "org.example.custom.room.config", "in": "path", "name": "type", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "example": { "custom_account_data_key": "custom_config_value" }, "type": "object" } } }, "description": "The account data content for the given type." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_INVALID_PARAM", "error": "@notaroomid:example.org is not a valid room ID." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Cannot add account data for other users." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The access token provided is not authorised to retrieve this user's account \ndata. Errcode: `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Room account data 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" ], "title": "Error", "type": "object" } } }, "description": "No account data has been provided for this user and this room with the \ngiven `type`. Errcode: `M_NOT_FOUND`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get some account data for the user that is specific to a room.", "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 delivered to\nclients in the per-room entries via [/sync](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv3sync).", "operationId": "setAccountDataPerRoom", "parameters": [ { "description": "The ID of the user to set account data for. The access token must be\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room to set account data on.", "example": "!726s6s6q:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The event type of the account data to set. Custom types should be\nnamespaced to avoid clashes.", "example": "org.example.custom.room.config", "in": "path", "name": "type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "custom_account_data_key": "custom_account_data_value" }, "type": "object" } } }, "description": "The content of the account data.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The account data was successfully added." }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_JSON", "error": "Content must be a JSON object." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The request body is not a JSON object (errcode `M_BAD_JSON` or\n`M_NOT_JSON`), or the given `roomID` is not a valid room ID\n(errcode `M_INVALID_PARAM`)." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_FORBIDDEN", "error": "Cannot add account data for other users." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The access token provided is not authorised to modify this user's account \ndata. Errcode: `M_FORBIDDEN`." }, "405": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_BAD_JSON", "error": "Cannot set m.fully_read through this API." } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "This `type` of account data is controlled by the server; it cannot be\nmodified by clients. Errcode: `M_BAD_JSON`." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Set some account data for the user that is specific to a room.", "tags": [ "User data" ] } }, "/_matrix/client/v3/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\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room to get tags for.", "example": "!726s6s6q:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "tags": { "m.favourite": { "order": 0.1 }, "u.Customers": {}, "u.Work": { "order": 0.7 } } } } }, "schema": { "properties": { "tags": { "additionalProperties": { "properties": { "order": { "description": "A number in a range `[0,1]` describing a relative\nposition of the room under the given tag.", "example": 0.25, "format": "float", "type": "number" } }, "title": "Tag", "type": "object" }, "type": "object" } }, "type": "object" } } }, "description": "The list of tags for the user for the room." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "List the tags for a room.", "tags": [ "User data" ] } }, "/_matrix/client/v3/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\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room to remove a tag from.", "example": "!726s6s6q:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The tag to remove.", "example": "u.work", "in": "path", "name": "tag", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The tag was successfully removed." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "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\nauthorised to make requests for this user ID.", "example": "@alice:example.com", "in": "path", "name": "userId", "required": true, "schema": { "type": "string" } }, { "description": "The ID of the room to add a tag to.", "example": "!726s6s6q:example.com", "in": "path", "name": "roomId", "required": true, "schema": { "type": "string" } }, { "description": "The tag to add.", "example": "u.work", "in": "path", "name": "tag", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "order": { "description": "A number in a range `[0,1]` describing a relative\nposition of the room under the given tag.", "example": 0.25, "format": "float", "type": "number" } }, "title": "Tag", "type": "object" } } }, "description": "Extra data for the tag, e.g. ordering.", "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The tag was successfully added." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Add a tag to a room.", "tags": [ "User data" ] } }, "/_matrix/client/v3/user_directory/search": { "post": { "description": "Performs a search for users. The homeserver may determine which\nsubset of users are searched. However, the homeserver MUST at a\nminimum consider users who are visible to the requester based\non their membership in rooms known to the homeserver. This means:\n\n- users that share a room with the requesting user\n- users who are joined to rooms known to the homeserver that have a\n `public` [join rule](#mroomjoin_rules)\n- users who are joined to rooms known to the homeserver that have a\n `world_readable` [history visibility](#room-history-visibility)\n\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", "requestBody": { "content": { "application/json": { "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" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris), if one exists.", "example": "mxc://bar.com/foo", "format": "uri", "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", "format": "mx-user-id", "pattern": "^@", "type": "string" } }, "required": [ "user_id" ], "title": "User", "type": "object" }, "type": "array" } }, "required": [ "results", "limited" ], "type": "object" } } }, "description": "The results of the search." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Searches the user directory.", "tags": [ "User directory" ] } }, "/_matrix/client/v3/users/{userId}/report": { "post": { "description": "Reports a user as inappropriate to the server, which may then notify\nthe appropriate people. How such information is delivered is left up to\nimplementations. The caller is not required to be joined to any rooms\nthat the reported user is joined to.\n\nClients may wish to [ignore](#ignoring-users) users after reporting them.\n\nClients could infer whether a reported user exists based on the 404 response.\nHomeservers that wish to conceal this information MAY return 200 responses\nregardless of the existence of the reported user.\n\nFurthermore, it might be possible for clients to deduce whether a reported\nuser exists by timing the response. This is because only a report for an\nexisting user will require the homeserver to do further processing. To\ncombat this, homeservers MAY add a random delay when generating a response.", "operationId": "reportUser", "parameters": [ { "description": "The user being reported.", "example": "@someguy:example.com", "in": "path", "name": "userId", "required": true, "schema": { "format": "mx-user-id", "pattern": "^@", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "example": { "reason": "this makes me sad" }, "properties": { "reason": { "description": "The reason the room is being reported. May be blank.", "type": "string" } }, "required": [ "reason" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The user has been reported successfully or the server chose\nto not disclose whether the users exists.\n" }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "The user was 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" ], "title": "Error", "type": "object" } } }, "description": "The user was not found on the homeserver." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Report a user as inappropriate.", "tags": [ "Reporting content" ], "x-addedInMatrixVersion": "1.14" } }, "/_matrix/client/v3/voip/turnServer": { "get": { "description": "This API provides credentials for the client to use when initiating\ncalls.", "operationId": "getTurnServer", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "format": "uri", "pattern": "^turns?:", "type": "string" }, "type": "array" }, "username": { "description": "The username to use.", "type": "string" } }, "required": [ "username", "password", "uris", "ttl" ], "type": "object" } } }, "description": "The TURN server credentials." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Obtain TURN server credentials.", "tags": [ "VOIP" ] } }, "/_matrix/client/versions": { "get": { "description": "Gets the versions of the specification supported by the server.\n\nValues will take the form `vX.Y` or `rX.Y.Z` in historical cases. See\n[the Specification Versioning](../#specification-versions) for more\ninformation.\n\nThe server may additionally advertise experimental features it supports\nthrough `unstable_features`. These features should be namespaced and\nmay optionally include version information within their name if desired.\nFeatures listed here are not for optionally toggling parts of the Matrix\nspecification and should only be used to advertise support for a feature\nwhich has not yet landed in the spec. For example, a feature currently\nundergoing the proposal process may appear here and eventually be taken\noff this list once the feature lands in the spec and the server deems it\nreasonable to do so. Servers can choose to enable some features only for\nsome users, so clients should include authentication in the request to\nget all the features available for the logged-in user. If no\nauthentication is provided, the server should only return the features\navailable to all users. Servers may wish to keep advertising features\nhere after they've been released into the spec to give clients a chance\nto upgrade appropriately. Additionally, clients should avoid using\nunstable features in their stable releases.", "operationId": "getVersions", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "unstable_features": { "org.example.my_feature": true }, "versions": [ "r0.0.1", "v1.1" ] } } }, "schema": { "properties": { "unstable_features": { "additionalProperties": { "description": "Whether or not the namespaced feature is supported.", "type": "boolean" }, "description": "Experimental features the server supports. Features not listed here,\nor the lack of this property all together, indicate that a feature is\nnot supported.", "type": "object" }, "versions": { "description": "The supported versions.", "items": { "description": "The supported versions", "type": "string" }, "type": "array" } }, "required": [ "versions" ], "type": "object" } } }, "description": "The versions supported by the server." } }, "security": [ {}, { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Gets the versions of the specification supported by the server.", "tags": [ "Server administration" ], "x-changedInMatrixVersion": { "1.10": "This endpoint can behave differently when authentication is provided.\n" } } }, "/_matrix/media/v1/create": { "post": { "description": "Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later\nvia [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](https://spec.matrix.org/v1.19/client-server-api/#put_matrixmediav3uploadservernamemediaid).\n\nThe server may optionally enforce a maximum age for unused IDs,\nand delete media IDs when the client doesn't start the upload in time,\nor when the upload was interrupted and not resumed in time. The server\nshould include the maximum POSIX millisecond timestamp to complete the\nupload in the `unused_expires_at` field in the response JSON. The\nrecommended default expiration is 24 hours which should be enough time\nto accommodate users on poor connection who find a better connection to\ncomplete the upload.\n\nAs well as limiting the rate of requests to create `mxc://` URIs, the server\nshould limit the number of concurrent *pending media uploads* a given\nuser can have. A pending media upload is a created `mxc://` URI where (a)\nthe media has not yet been uploaded, and (b) has not yet expired (the\n`unused_expires_at` timestamp has not yet passed). In both cases, the\nserver should respond with an HTTP 429 error with an errcode of\n`M_LIMIT_EXCEEDED`.", "operationId": "createContent", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "content_uri": { "description": "The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) at\nwhich the content will be available, once it is uploaded.", "example": "mxc://example.com/AQwafuaFswefuhsfAFAgsw", "format": "mx-mxc-uri", "pattern": "^mxc:\\/\\/", "type": "string" }, "unused_expires_at": { "description": "The timestamp (in milliseconds since the unix epoch) when the\ngenerated media id will expire, if media is not uploaded.", "example": 1647257217083, "format": "int64", "type": "integer" } }, "required": [ "content_uri" ], "type": "object" } } }, "description": "The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) for the uploaded content." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The user does not have permission to upload the content." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Create a new `mxc://` URI without uploading the content.", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.7" } }, "/_matrix/media/v3/config": { "get": { "deprecated": true, "description": "**NOTE:** \nReplaced by [`GET /_matrix/client/v1/media/config`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mediaconfig).\n\n\nThis 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", "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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" } } }, "description": "The public content repository configuration for the matrix server." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get the configuration for the content repository.", "tags": [ "Media" ] } }, "/_matrix/media/v3/download/{serverName}/{mediaId}": { "get": { "deprecated": true, "description": "**NOTE:** \nReplaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mediadownloadservernamemediaid)\n(requires authentication).\n\n\n**WARNING:** \n**[Changed in `v1.11`]** This endpoint MAY return `404 M_NOT_FOUND`\nfor media which exists, but is after the server froze unauthenticated\nmedia access. See [Client Behaviour](https://spec.matrix.org/v1.19/client-server-api/#content-repo-client-behaviour) for more\ninformation.\n", "operationId": "getContent", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "Indicates to the server that it should not attempt to fetch the media if\nit is deemed remote. This is to prevent routing loops where the server\ncontacts itself.\n\nDefaults to `true` if not provided.", "example": false, "in": "query", "name": "allow_remote", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" }, { "description": "Indicates to the server that it may return a 307 or 308 redirect\nresponse that points at the relevant media content. When not explicitly\nset to `true` the server must return the media content itself.\n", "example": false, "in": "query", "name": "allow_redirect", "required": false, "schema": { "default": false, "type": "boolean" }, "x-addedInMatrixVersion": "1.7" } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "**Required.** The bytes for the uploaded file." } } }, "description": "The content that was previously uploaded.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be one of `inline` or `attachment`,\nand SHOULD contain a file name.\n\nIf the `Content-Type` is allowed in the [restrictions for serving\ninline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nservers SHOULD use `inline`, otherwise they SHOULD use\n`attachment`.\n\nIf the upload was made with a `filename`, this header MUST\ncontain the same `filename`. Otherwise, `filename` is excluded\nfrom the header. If the media being downloaded is remote, the\nremote server's `filename` in the `Content-Disposition` header\nis used as the `filename` instead. When the header is not\nsupplied, or does not supply a `filename`, the local download\nresponse does not include a `filename`.\n", "required": true, "schema": { "example": "inline; filename=\"filename.jpg\"", "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required." } }, "Content-Type": { "description": "The content type of the file that was previously uploaded.\n\nThe server MUST return a `Content-Type` which is either exactly the same\nas the original upload, or reasonably close. The bounds of \"reasonable\"\nare:\n\n* Adding a charset to `text/*` content types.\n* Detecting HTML and using `text/html` instead of `text/plain`.\n* Using `application/octet-stream` when the server determines the\n content type is obviously wrong. For example, an encrypted file being\n claimed as `image/png`.\n* Returning `application/octet-stream` when the media has an\n unknown/unprovided `Content-Type`. For example, being uploaded before\n the server tracked content types or when the remote server is\n non-compliantly omitting the header entirely.\n\nActions not in the spirit of the above are not considered \"reasonable\".\n", "required": true, "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`,\nand the behaviour to compute its value was clarified.\n" } } } }, "307": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The content is too large for the server to serve." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "summary": "Download content from the content repository.", "tags": [ "Media" ] } }, "/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}": { "get": { "deprecated": true, "description": "**NOTE:** \nReplaced by [`GET /_matrix/client/v1/media/download/{serverName}/{mediaId}/{fileName}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mediadownloadservernamemediaidfilename)\n(requires authentication).\n\n\nThis will download content from the content repository (same as\nthe previous endpoint) but replace the target file name with the one\nprovided by the caller.\n\n**WARNING:** \n**[Changed in `v1.11`]** This endpoint MAY return `404 M_NOT_FOUND`\nfor media which exists, but is after the server froze unauthenticated\nmedia access. See [Client Behaviour](https://spec.matrix.org/v1.19/client-server-api/#content-repo-client-behaviour) for more\ninformation.\n", "operationId": "getContentOverrideName", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "A filename to give in the `Content-Disposition` header.", "example": "filename.jpg", "in": "path", "name": "fileName", "required": true, "schema": { "type": "string" } }, { "description": "Indicates to the server that it should not attempt to fetch the media if\nit is deemed remote. This is to prevent routing loops where the server\ncontacts itself.\n\nDefaults to `true` if not provided.", "example": false, "in": "query", "name": "allow_remote", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" }, { "description": "Indicates to the server that it may return a 307 or 308 redirect\nresponse that points at the relevant media content. When not explicitly\nset to `true` the server must return the media content itself.\n", "example": false, "in": "query", "name": "allow_redirect", "required": false, "schema": { "default": false, "type": "boolean" }, "x-addedInMatrixVersion": "1.7" } ], "responses": { "200": { "content": { "application/octet-stream": { "schema": { "description": "**Required.** The bytes for the uploaded file." } } }, "description": "The content that was previously uploaded.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be one of `inline` or `attachment`,\nand MUST contain the file name requested in the path.\n\nIf the `Content-Type` is allowed in the [restrictions for serving\ninline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nservers SHOULD use `inline`, otherwise they SHOULD use\n`attachment`.\n", "required": true, "schema": { "example": "inline; filename=\"filename.jpg\"", "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required." } }, "Content-Type": { "description": "The content type of the file that was previously uploaded.\n\nThe server MUST return a `Content-Type` which is either exactly the same\nas the original upload, or reasonably close. The bounds of \"reasonable\"\nare:\n\n* Adding a charset to `text/*` content types.\n* Detecting HTML and using `text/html` instead of `text/plain`.\n* Using `application/octet-stream` when the server determines the\n content type is obviously wrong. For example, an encrypted file being\n claimed as `image/png`.\n* Returning `application/octet-stream` when the media has an\n unknown/unprovided `Content-Type`. For example, being uploaded before\n the server tracked content types or when the remote server is\n non-compliantly omitting the header entirely.\n\nActions not in the spirit of the above are not considered \"reasonable\".\n", "required": true, "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`,\nand the behaviour to compute its value was clarified.\n" } } } }, "307": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the requested content.", "headers": { "Location": { "description": "The URL of the content.", "schema": { "format": "uri", "type": "string" } } } }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The content is too large for the server to serve." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "summary": "Download content from the content repository overriding the file name", "tags": [ "Media" ] } }, "/_matrix/media/v3/preview_url": { "get": { "deprecated": true, "description": "**NOTE:** \nReplaced by [`GET /_matrix/client/v1/media/preview_url`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mediapreview_url).\n\n\nGet 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:**\nClients should consider avoiding this endpoint for URLs posted in encrypted\nrooms. Encrypted rooms often contain more sensitive information the users\ndo not want to share with the homeserver, and this can mean that the URLs\nbeing shared should also not be shared with the homeserver.", "operationId": "getUrlPreview", "parameters": [ { "description": "The URL to get a preview of.", "example": "https://matrix.org", "in": "query", "name": "url", "required": true, "schema": { "format": "uri", "type": "string" } }, { "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.", "example": 1510610716656, "in": "query", "name": "ts", "schema": { "format": "int64", "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "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": { "additionalProperties": { "description": "Additional properties as per the [OpenGraph](https://ogp.me/) protocol." }, "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](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image.", "format": "uri", "type": "string" } }, "type": "object" } } }, "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](https://ogp.me/) protocol are\ndescribed here." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Get information about a URL for a client", "tags": [ "Media" ] } }, "/_matrix/media/v3/thumbnail/{serverName}/{mediaId}": { "get": { "deprecated": true, "description": "**NOTE:** \nReplaced by [`GET /_matrix/client/v1/media/thumbnail/{serverName}/{mediaId}`](https://spec.matrix.org/v1.19/client-server-api/#get_matrixclientv1mediathumbnailservernamemediaid)\n(requires authentication).\n\n\nDownload a thumbnail of content from the content repository.\nSee the [Thumbnails](https://spec.matrix.org/v1.19/client-server-api/#thumbnails) section for more information.\n\n**WARNING:** \n**[Changed in `v1.11`]** This endpoint MAY return `404 M_NOT_FOUND`\nfor media which exists, but is after the server froze unauthenticated\nmedia access. See [Client Behaviour](https://spec.matrix.org/v1.19/client-server-api/#content-repo-client-behaviour) for more\ninformation.\n", "operationId": "getContentThumbnail", "parameters": [ { "description": "The server name from the `mxc://` URI (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "The *desired* width of the thumbnail. The actual thumbnail may be\nlarger than the size specified.", "example": 64, "in": "query", "name": "width", "required": true, "schema": { "type": "integer" } }, { "description": "The *desired* height of the thumbnail. The actual thumbnail may be\nlarger than the size specified.", "example": 64, "in": "query", "name": "height", "required": true, "schema": { "type": "integer" } }, { "description": "The desired resizing method. See the [Thumbnails](https://spec.matrix.org/v1.19/client-server-api/#thumbnails)\nsection for more information.", "example": "scale", "in": "query", "name": "method", "schema": { "enum": [ "crop", "scale" ], "type": "string" } }, { "description": "Indicates to the server that it should not attempt to fetch the media if\nit is deemed remote. This is to prevent routing loops where the server\ncontacts itself.\n\nDefaults to `true` if not provided.", "example": false, "in": "query", "name": "allow_remote", "required": false, "schema": { "default": true, "type": "boolean" } }, { "description": "The maximum number of milliseconds that the client is willing to wait to\nstart receiving data, in the case that the content has not yet been\nuploaded. The default value is 20000 (20 seconds). The content\nrepository SHOULD impose a maximum value for this parameter. The\ncontent repository MAY respond before the timeout.\n", "example": 5000, "in": "query", "name": "timeout_ms", "schema": { "default": 20000, "format": "int64", "type": "integer" }, "x-addedInMatrixVersion": "1.7" }, { "description": "Indicates to the server that it may return a 307 or 308 redirect\nresponse that points at the relevant media content. When not explicitly\nset to `true` the server must return the media content itself.\n", "example": false, "in": "query", "name": "allow_redirect", "required": false, "schema": { "default": false, "type": "boolean" }, "x-addedInMatrixVersion": "1.7" }, { "description": "Indicates preference for an animated thumbnail from the server, if possible. Animated\nthumbnails typically use the content types `image/gif`, `image/png` (with APNG format),\n`image/apng`, and `image/webp` instead of the common static `image/png` or `image/jpeg`\ncontent types.\n\nWhen `true`, the server SHOULD return an animated thumbnail if possible and supported.\nWhen `false`, the server MUST NOT return an animated thumbnail. For example, returning a\nstatic `image/png` or `image/jpeg` thumbnail. When not provided, the server SHOULD NOT\nreturn an animated thumbnail.\n\nServers SHOULD prefer to return `image/webp` thumbnails when supporting animation.\n\nWhen `true` and the media cannot be animated, such as in the case of a JPEG or PDF, the\nserver SHOULD behave as though `animated` is `false`.\n", "example": false, "in": "query", "name": "animated", "required": false, "schema": { "type": "boolean" }, "x-addedInMatrixVersion": "1.11" } ], "responses": { "200": { "content": { "image/apng": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } }, "image/gif": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } }, "image/jpeg": { "schema": { "description": "**Required.** The bytes for the thumbnail." } }, "image/png": { "schema": { "description": "**Required.** The bytes for the thumbnail. The thumbnail MAY use an animated\nformat if `animated=true`.\n", "x-changedInMatrixVersion": { "1.11": "The PNG may be of the APNG variety if animation is supported and requested." } } }, "image/webp": { "schema": { "description": "**Required.** The bytes for the *animated* thumbnail.", "x-addedInMatrixVersion": "1.11" } } }, "description": "A thumbnail of the requested content.", "headers": { "Content-Disposition": { "description": "The [disposition](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition)\nof the returned content. MUST be `inline`, and SHOULD contain a file name (e.g. `thumbnail.png`).\n\nServers should note the [Content-Type restrictions for serving inline content](https://spec.matrix.org/v1.19/client-server-api/#serving-inline-content),\nas these limitations imply which formats should be used for thumbnail generation.\n", "required": true, "schema": { "example": "inline; filename=\"thumbnail.png\"", "type": "string" }, "x-addedInMatrixVersion": "1.12" }, "Content-Type": { "description": "The content type of the thumbnail.", "required": true, "schema": { "enum": [ "image/jpeg", "image/png", "image/apng", "image/gif", "image/webp" ], "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became required in order to support `Content-Disposition`.\n" } } } }, "307": { "description": "A redirect to the thumbnail of the requested content.", "headers": { "Location": { "description": "The URL of the thumbnail content.", "schema": { "format": "uri", "type": "string" } } } }, "308": { "description": "A redirect to the thumbnail of the requested content.", "headers": { "Location": { "description": "The URL of the thumbnail content.", "schema": { "format": "uri", "type": "string" } } } }, "400": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "413": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The local content is too large for the server to thumbnail." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." }, "502": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The remote content is too large for the server to thumbnail." }, "504": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_YET_UPLOADED", "error": "Content has not yet been uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The content is not yet available. A [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_YET_UPLOADED`." } }, "summary": "Download a thumbnail of content from the content repository", "tags": [ "Media" ] } }, "/_matrix/media/v3/upload": { "post": { "operationId": "uploadContent", "parameters": [ { "description": "**Optional.** The content type of the file being uploaded.\n\nClients SHOULD always supply this header.\n\nDefaults to `application/octet-stream` if it is not set.\n", "example": "application/pdf", "in": "header", "name": "Content-Type", "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became explicitly optional with a default value.\n" } }, { "description": "The name of the file being uploaded", "example": "War and Peace.pdf", "in": "query", "name": "filename", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "description": "The content to be uploaded.", "example": "" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": { "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw" } } }, "schema": { "properties": { "content_uri": { "description": "The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) to the uploaded content.", "format": "mx-mxc-uri", "pattern": "^mxc:\\/\\/", "type": "string" } }, "required": [ "content_uri" ], "type": "object" } } }, "description": "The [`mxc://` URI](https://spec.matrix.org/v1.19/client-server-api/#matrix-content-mxc-uris) for the uploaded content." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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." }, "413": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The uploaded content is too large for the server." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload some content to the content repository.", "tags": [ "Media" ] } }, "/_matrix/media/v3/upload/{serverName}/{mediaId}": { "put": { "description": "This endpoint permits uploading content to an `mxc://` URI that was created\nearlier via [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create).", "operationId": "uploadContentToMXC", "parameters": [ { "description": "The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authority component).\n", "example": "matrix.org", "in": "path", "name": "serverName", "required": true, "schema": { "format": "mx-server-name", "type": "string" } }, { "description": "The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component).\n", "example": "ascERGshawAWawugaAcauga", "in": "path", "name": "mediaId", "required": true, "schema": { "type": "string" } }, { "description": "**Optional.** The content type of the file being uploaded.\n\nClients SHOULD always supply this header.\n\nDefaults to `application/octet-stream` if it is not set.\n", "example": "application/pdf", "in": "header", "name": "Content-Type", "schema": { "type": "string" }, "x-changedInMatrixVersion": { "1.12": "This header became explicitly optional with a default value.\n" } }, { "description": "The name of the file being uploaded", "example": "War and Peace.pdf", "in": "query", "name": "filename", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/octet-stream": { "schema": { "description": "The content to be uploaded.", "example": "" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "response": { "value": {} } }, "schema": { "type": "object" } } }, "description": "The upload was successful." }, "403": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "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.\n- The request comes from a different user than the one that called\n [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create).\n\nA [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_FORBIDDEN`." }, "404": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_NOT_FOUND", "error": "Unknown media ID" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The user has provided an invalid MXC ID. Some reasons for this error include:\n\n- The MXC ID was not created with [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.19/client-server-api/#post_matrixmediav1create).\n- The MXC ID has expired.\n\nA [standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_NOT_FOUND`." }, "409": { "content": { "application/json": { "examples": { "response": { "value": { "errcode": "M_CANNOT_OVERWRITE_MEDIA", "error": "Media already uploaded" } } }, "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" ], "title": "Error", "type": "object" } } }, "description": "The endpoint was called with a media ID that already has content. A\n[standard error response](https://spec.matrix.org/v1.19/client-server-api/#standard-error-response)\nwill be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`." }, "413": { "content": { "application/json": { "examples": { "response": { "value": { "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" ], "title": "Error", "type": "object" } } }, "description": "The uploaded content is too large for the server." }, "429": { "content": { "application/json": { "schema": { "allOf": [ { "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" ], "title": "Error", "type": "object" }, { "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" ], "title": "RateLimitError", "type": "object" } ] } } }, "description": "This request was rate-limited." } }, "security": [ { "accessTokenQuery": [] }, { "accessTokenBearer": [] } ], "summary": "Upload content to an `mxc://` URI that was created earlier.", "tags": [ "Media" ], "x-addedInMatrixVersion": "1.7" } } }, "servers": [ { "url": "https://matrix.org" }, { "url": "https://{homeserver_address}", "variables": { "homeserver_address": { "default": "matrix-client.matrix.org", "description": "The base URL for your homeserver" } } } ] }