Skip to content

Instantly share code, notes, and snippets.

@teyfix

teyfix/client-server.json

Last active June 20, 2025 18:01
Show Gist options
  • Save teyfix/4d6e24c4f13496319e28bdee9aaf0ccb to your computer and use it in GitHub Desktop.
Save teyfix/4d6e24c4f13496319e28bdee9aaf0ccb to your computer and use it in GitHub Desktop.
Download ZIP
matrix-spec
Raw
client-server.json
This file has been truncated, but you can view the full file.
{
"components": {
"securitySchemes": {
"accessTokenBearer": {
"description": "The `access_token` returned by a call to `/login` or `/register`, using the\n`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` returned by a call to `/login` or `/register`, as a query\nparameter.\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": "unstable"
},
"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/unstable/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/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/unstable/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/unstable/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": "[email protected]",
"matrix_id": "@admin:example.org",
"role": "m.role.admin"
},
{
"email_address": "[email protected]",
"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": "[email protected]",
"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/unstable/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/unstable/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/appservice/{appserviceId}/ping": {
"post": {
"description": "This API asks the homeserver to call the\n[`/_matrix/app/v1/ping`](https://spec.matrix.org/unstable/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/unstable/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/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/unstable/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/unstable/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/unstable/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/unstable/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": "<opaque string>"
}
}
},
"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/unstable/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/unstable/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/unstable/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/unstable/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/unstable/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/unstable/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": {
"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/unstable/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 are described 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/unstable/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/unstable/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/unstable/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/unstable/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/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/unstable/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/unstable/client-server-api/#mroomtopic).",
"example": "All things general",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest 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/unstable/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/unstable/client-server-api/#mroomcreate)), if any.",
"type": "string"
},
"room_version": {
"description": "The version of the room.",
"type": "string"
}
},
"type": "object"
}
],
"required": [
"room_id",
"num_joined_members",
"world_readable",
"guest_can_join"
],
"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.",
"required": [
"guest_can_join",
"num_joined_members",
"room_id",
"world_readable"
]
}
}
},
"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/unstable/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/unstable/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/unstable/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/unstable/client-server-api/#mroomtopic).",
"example": "All things general",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest 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/unstable/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/unstable/client-server-api/#mroomcreate)), if any.",
"type": "string"
},
"room_version": {
"description": "The version of the room.",
"type": "string"
}
},
"type": "object"
}
],
"required": [
"room_id",
"num_joined_members",
"world_readable",
"guest_can_join"
],
"title": "RoomSummary",
"type": "object"
},
{
"properties": {
"allowed_room_ids": {
"x-addedInMatrixVersion": "1.15"
},
"children_state": {
"description": "The [`m.space.child`](https://spec.matrix.org/unstable/client-server-api/#mspacechild) events of the space-room, represented\nas [Stripped State Events](https://spec.matrix.org/unstable/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": [
{
"description": "A stripped down state event, with only the `type`, `state_key`,\n`sender`, and `content` keys.",
"properties": {
"content": {
"description": "The `content` for the event.",
"title": "EventContent",
"type": "object"
},
"sender": {
"description": "The `sender` for the event.",
"type": "string"
},
"state_key": {
"description": "The `state_key` for the event.",
"type": "string"
},
"type": {
"description": "The `type` for the event.",
"type": "string"
}
},
"required": [
"type",
"state_key",
"content",
"sender"
],
"title": "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": {
"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": {
"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/unstable/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/unstable/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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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": {
"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": {
"type": "string"
}
},
{
"description": "The [relationship type](https://spec.matrix.org/unstable/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/unstable/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/unstable/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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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": {
"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": {
"type": "string"
}
},
{
"description": "The [relationship type](https://spec.matrix.org/unstable/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/unstable/client-server-api/#get_matrixclientv3roomsroomidmessages),\nor a `next_batch` token from [`/sync`](https://spec.matrix.org/unstable/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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/unstable/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": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"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/unstable/client-server-api/#aggregations-of-child-events).\n\nIf the thread root event was sent by an [ignored user](https://spec.matrix.org/unstable/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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/unstable/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/unstable/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": {
"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",
"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": "[email protected]",
"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.",
"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/unstable/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.",
"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/unstable/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.",
"operationId": "delete3pidFromAccount",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"address": {
"description": "The third-party address being removed.",
"example": "[email protected]",
"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/unstable/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": "[email protected]",
"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 to, with identical parameters to the Identity Service\nAPI's `POST /validate/email/submitToken` endpoint (without the requirement\nfor an access token). The homeserver must send this token to the user (if\napplicable), who should then be prompted 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 this specification version in the `/versions` response\n(ie: r0.5.0).",
"example": "https://example.org/path/to/submitToken",
"format": "uri",
"type": "string"
}
},
"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/unstable/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 to, with identical parameters to the Identity Service\nAPI's `POST /validate/email/submitToken` endpoint (without the requirement\nfor an access token). The homeserver must send this token to the user (if\napplicable), who should then be prompted 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 this specification version in the `/versions` response\n(ie: r0.5.0).",
"example": "https://example.org/path/to/submitToken",
"format": "uri",
"type": "string"
}
},
"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": "[email protected]",
"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/unstable/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.",
"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/unstable/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/unstable/client-server-api/#client-config)\nand [contact 3PIDs](https://spec.matrix.org/unstable/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/unstable/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.",
"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/unstable/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/unstable/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/unstable/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": "[email protected]",
"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 to, with identical parameters to the Identity Service\nAPI's `POST /validate/email/submitToken` endpoint (without the requirement\nfor an access token). The homeserver must send this token to the user (if\napplicable), who should then be prompted 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 this specification version in the `/versions` response\n(ie: r0.5.0).",
"example": "https://example.org/path/to/submitToken",
"format": "uri",
"type": "string"
}
},
"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/unstable/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 to, with identical parameters to the Identity Service\nAPI's `POST /validate/email/submitToken` endpoint (without the requirement\nfor an access token). The homeserver must send this token to the user (if\napplicable), who should then be prompted 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 this specification version in the `/versions` response\n(ie: r0.5.0).",
"example": "https://example.org/path/to/submitToken",
"format": "uri",
"type": "string"
}
},
"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/unstable/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/unstable/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.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.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.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": {
"description": "Capability to indicate if the user can change their avatar.",
"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": {
"description": "Capability to indicate if the user can change their display name.",
"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, giving the room creator\n (and not other members) permission to send state events. Overridden\n by the `power_level_content_override` parameter.\n\n4. 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`.",
"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/unstable/client-server-api/#mroomcreate) event. The server will overwrite the following\nkeys: `creator`, `room_version`. Future versions of the specification\nmay allow the server to overwrite other keys.",
"title": "CreationContent",
"type": "object"
},
"initial_state": {
"description": "A list of state events to set in the new room. This allows\nthe user to override the default state events set in the new\nroom. The expected format of the state events are an object\nwith type, state_key and content keys set.\n\nTakes precedence over events set by `preset`, but gets\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": {
"type": "string"
},
"type": "array"
},
"invite_3pid": {
"description": "A list of objects representing third-party IDs to invite into\nthe room.",
"items": {
"example": {
"address": "[email protected]",
"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/unstable/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/unstable/client-server-api/#direct-messaging) for more information.",
"type": "boolean"
},
"name": {
"description": "If this is included, an [`m.room.name`](https://spec.matrix.org/unstable/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/unstable/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/unstable/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/unstable/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/unstable/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/unstable/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.",
"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": "\nThe request is invalid. A meaningful `errcode` and description\nerror text will be returned. Example reasons for rejection include:\n\n- The request body is malformed (`errcode` set to `M_BAD_JSON`\n or `M_NOT_JSON`).\n\n- The room alias specified is already taken (`errcode` set to\n `M_ROOM_IN_USE`).\n\n- The initial state implied by the parameters to the request is\n invalid: for example, the user's `power_level` is set below\n that necessary to set the room name (`errcode` set to\n `M_INVALID_ROOM_STATE`).\n\n- The homeserver doesn't support the requested room version, or\n one or more users being invited to the new room are residents\n of a homeserver which does not support the requested room version.\n The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these\n cases."
}
},
"security": [
{
"accessTokenQuery": []
},
{
"accessTokenBearer": []
}
],
"summary": "Create a new room",
"tags": [
"Room creation"
]
}
},
"/_matrix/client/v3/delete_devices": {
"post": {
"description": "This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/unstable/client-server-api/#user-interactive-authentication-api).\n\nDeletes the given devices, and invalidates any access token associated with them.",
"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/unstable/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"
]
}
},
"/_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/unstable/client-server-api/#user-interactive-authentication-api).\n\nDeletes the given device, and invalidates any access token associated with it.",
"operationId": "deleteDevice",
"parameters": [
{
"description": "The device to delete.",
"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/unstable/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"
]
},
"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.",
"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."
},
"404": {
"description": "The current user has no device with the given ID."
}
},
"security": [
{
"accessTokenQuery": []
},
{
"accessTokenBearer": []
}
],
"summary": "Update a device",
"tags": [
"Device management"
]
}
},
"/_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/unstable/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": {
"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": {
"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/unstable/appendices/#room-aliases).\n",
"example": "#monkeys:matrix.org",
"in": "path",
"name": "roomAlias",
"required": true,
"schema": {
"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/unstable/appendices/#room-aliases).\n",
"example": "#monkeys:matrix.org",
"in": "path",
"name": "roomAlias",
"required": true,
"schema": {
"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.",
"type": "string"
},
"servers": {
"description": "A list of servers that are aware of this room alias.",
"items": {
"description": "A server which is aware of this room alias.",
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
},
"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/unstable/appendices/#room-aliases).\n",
"example": "#monkeys:matrix.org",
"in": "path",
"name": "roomAlias",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"example": {
"room_id": "!abnjk1jdasj98:capuchins.com"
},
"properties": {
"room_id": {
"description": "The room ID to set.",
"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/unstable/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": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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",
"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": "<b>This is an example text message</b>",
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/unstable/client-server-api/#get_matrixclientv3roomsroomideventeventid) API\nor the [/rooms/{roomId}/context/{eventId](https://spec.matrix.org/unstable/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": {
"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": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/unstable/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": "<b>This is an example text message</b>",
"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": {
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type",
"content"
],
"title": "Event",
"type": "object"
},
"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": {
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type",
"content"
],
"title": "Event",
"type": "object"
},
"type": "array"
},
"rooms": {
"items": {
"properties": {
"account_data": {
"description": "The private data that this user has attached to\nthis room.",
"items": {
"description": "The basic set of fields all events must have.",
"properties": {
"content": {
"description": "The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.",
"type": "object"
},
"type": {
"description": "The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'",
"type": "string"
}
},
"required": [
"type",
"content"
],
"title": "Event",
"type": "object"
},
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/<room_id>/messages`](https://spec.matrix.org/unstable/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/<room_id>/messages`](https://spec.matrix.org/unstable/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.",
"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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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",
"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/unstable/client-server-api/#get_matrixclientv3initialsync)\nand [`/sync`](https://spec.matrix.org/unstable/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": {
"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": {
"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",
"type": "string"
},
"sender": {
"description": "The Matrix ID of the user who issued the invite.",
"example": "@alice:example.org",
"type": "string"
},
"signatures": {
"additionalProperties": {
"additionalProperties": {
"type": "string"
},
"type": "object"
},
"description": "A signatures object containing a signature of the entire signed object.",
"example": {
"example.org": {
"ed25519:0": "some9signature"
}
},
"title": "Signatures",
"type": "object"
},
"token": {
"description": "The state key of the m.third_party_invite event.",
"example": "random8nonce",
"type": "string"
}
},
"required": [
"sender",
"mxid",
"token",
"signatures"
],
"title": "Third-party Signed",
"type": "object"
}
],
"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.",
"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": {
"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/unstable/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/unstable/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/unstable/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 `<algorithm>:<key_id>` to the key object.\n\nSee the [key algorithms](https://spec.matrix.org/unstable/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/unstable/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`<algorithm>:<key_id>`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/unstable/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/unstable/client-server-api/#user-interactive-authentication-api).\n\nUser-Interactive Authentication MUST be performed, except in these cases:\n- there is no existing cross-signing master key uploaded to the homeserver, OR\n- there is an existing cross-signing master key and it exactly matches the\n cross-signing master 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.",
"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/unstable/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": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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 key."
},
"self_signing_key": {
"allOf": [
{
"description": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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 key, or by the user\\'s most recently\nuploaded master key if no master key is included in the\nrequest."
},
"user_signing_key": {
"allOf": [
{
"description": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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 key, or by the user\\'s most recently\nuploaded master key if no master 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 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 authorized 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."
}
}
},
"/_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 `<algorithm>:<device_id>`. The keys themselves should be\nencoded as specified by the key algorithm.",
"example": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"type": "object"
},
"signatures": {
"description": "Signatures for the device key object. A map from user ID, to a map from\n`<algorithm>:<device_id>` to the signature.\n\nThe signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/unstable/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 cross-signing keys of the queried users.\nA map from user ID, to master 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": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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": "Cross signing key",
"properties": {
"keys": {
"additionalProperties": {
"type": "string"
},
"description": "The public key. The object must have exactly one property, whose name is\nin the form `<algorithm>:<unpadded_base64_public_key>`, 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/unstable/appendices/#signing-json).\nOptional for the master key. Other keys must be signed by the\nuser\\'s master 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-sha256",
"m.megolm.v1.aes-sha"
],
"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 `<algorithm>:<device_id>`. The keys themselves should be\nencoded as specified by the key algorithm.",
"example": {
"curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
"ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
},
"type": "object"
},
"signatures": {
"description": "Signatures for the device key object. A map from user ID, to a map from\n`<algorithm>:<device_id>` to the signature.\n\nThe signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/unstable/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/unstable/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`<algorithm>:<key_id>`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/unstable/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/unstable/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`<algorithm>:<key_id>`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/unstable/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`<algorithm>:<key_id>`. The format of the key is determined\nby the [key algorithm](https://spec.matrix.org/unstable/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/unstable/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": {
"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": {
"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.",
"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/unstable/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"
},
"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 authorize themself in subsequent requests.\n\nIf the client does not supply a `device_id`, the server must\nauto-generate one.\n\nThe returned access token must be associated with the `device_id`\nsupplied by the client or generated by the server. The server may\ninvalidate any access token previously associated with that device. See\n[Relationship between access tokens and devices](https://spec.matrix.org/unstable/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/unstable/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/unstable/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/unstable/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 authorize other requests.",
"type": "string"
},
"device_id": {
"description": "ID of the logged-in device. Will be the same as the\ncorresponding parameter in the request, if one was specified.",
"type": "string"
},
"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."
},
"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."
},
"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"
}
}
],
"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"
}
}
],
"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\nauthorization. The device associated with the access token is also deleted.\n[Device keys](https://spec.matrix.org/unstable/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\nauthorization. This includes the access token that made this request. All devices\nfor the user are also deleted. [Device keys](https://spec.matrix.org/unstable/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/unstable/client-server-api/#user-interactive-authentication-api) because\nUser-Interactive Authentication is designed to protect against attacks where the\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": "<b>This is an example text message</b>",
"msgtype": "m.text"
},
"event_id": "$143273582443PhrSn:example.org",
"origin_server_ts": 1432735824653,
"room_id": "!jEsUZKDJdhlrceRyVU:example.org",
"sender": "@example:example.org",
"type": "m.room.message",
"unsigned": {
"age": 1234,
"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/unstable/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",
"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",
"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/unstable/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 previous `content` for this event. This field is generated\nby the local homeserver, and is only returned if the event is a state event,\nand the client has permission to see the previous content.\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/unstable/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"
},
"transaction_id": {
"description": "The client-supplied [transaction ID](https://spec.matrix.org/unstable/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 combined profile information for this user. This API may be used\nto fetch the user's own profile information or other users; either\nlocally or on remote homeservers.",
"operationId": "getUserProfile",
"parameters": [
{
"description": "The user whose profile information to get.",
"example": "@alice:example.com",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg",
"displayname": "Alice Margatroid"
}
}
},
"schema": {
"properties": {
"avatar_url": {
"description": "The user's avatar URL if they have set one, otherwise not present.",
"format": "uri",
"type": "string"
},
"displayname": {
"description": "The user's display name if they have set one, otherwise not present.",
"type": "string"
}
},
"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 this user's profile information.",
"tags": [
"User data"
]
}
},
"/_matrix/client/v3/profile/{userId}/avatar_url": {
"get": {
"description": "Get the user's avatar URL. This API may be used to fetch the user's\nown avatar URL or to query the URL of other users; either locally or\non remote homeservers.",
"operationId": "getAvatarUrl",
"parameters": [
{
"description": "The user whose avatar URL to get.",
"example": "@alice:example.com",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": {
"avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}
}
},
"schema": {
"properties": {
"avatar_url": {
"description": "The user's avatar URL if they have set one, otherwise not present.",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
}
},
"description": "The avatar URL 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 an avatar URL.",
"x-addedInMatrixVersion": "1.12"
},
"404": {
"description": "There is no avatar URL for this user or this user does not exist."
}
},
"summary": "Get the user's avatar URL.",
"tags": [
"User data"
]
},
"put": {
"description": "This API sets the given user's avatar URL. You must have permission to\nset this user's avatar URL, e.g. you need to have their `access_token`.",
"operationId": "setAvatarUrl",
"parameters": [
{
"description": "The user whose avatar URL to set.",
"example": "@alice:example.com",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"example": {
"avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
},
"properties": {
"avatar_url": {
"description": "The new avatar URL for this user.",
"format": "uri",
"type": "string"
}
},
"type": "object"
}
}
},
"description": "The new avatar information.",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": {}
}
},
"schema": {
"type": "object"
}
}
},
"description": "The avatar URL 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": "Set the user's avatar URL.",
"tags": [
"User data"
]
}
},
"/_matrix/client/v3/profile/{userId}/displayname": {
"get": {
"description": "Get the user's display name. This API may be used to fetch the user's\nown displayname or to query the name of other users; either locally or\non remote homeservers.",
"operationId": "getDisplayName",
"parameters": [
{
"description": "The user whose display name to get.",
"example": "@alice:example.com",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": {
"displayname": "Alice Margatroid"
}
}
},
"schema": {
"properties": {
"displayname": {
"description": "The user's display name if they have set one, otherwise not present.",
"type": "string"
}
},
"type": "object"
}
}
},
"description": "The display name 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 a display name.",
"x-addedInMatrixVersion": "1.12"
},
"404": {
"description": "There is no display name for this user or this user does not exist."
}
},
"summary": "Get the user's display name.",
"tags": [
"User data"
]
},
"put": {
"description": "This API sets the given user's display name. You must have permission to\nset this user's display name, e.g. you need to have their `access_token`.",
"operationId": "setDisplayName",
"parameters": [
{
"description": "The user whose display name to set.",
"example": "@alice:example.com",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"example": {
"displayname": "Alice Margatroid"
},
"properties": {
"displayname": {
"description": "The new display name for this user.",
"type": "string"
}
},
"type": "object"
}
}
},
"description": "The new display name information.",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"examples": {
"response": {
"value": {}
}
},
"schema": {
"type": "object"
}
}
},
"description": "The display name 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": "Set the user's display name.",
"tags": [
"User data"
]
}
},
"/_matrix/client/v3/publicRooms": {
"get": {
"description": "Lists a server's published room directory.\n\nThis API returns paginated responses. The rooms are ordered by the number\nof joined members, with the largest rooms first.",
"operationId": "getPublicRooms",
"parameters": [
{
"description": "Limit the number of results returned.",
"in": "query",
"name": "limit",
"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": {
"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/unstable/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/unstable/client-server-api/#mroomtopic).",
"example": "All things general",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest 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. The rooms are ordered by the number\nof joined members, with the largest rooms first.",
"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": {
"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/unstable/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/unstable/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/unstable/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/unstable/client-server-api/#mroomtopic).",
"example": "All things general",
"type": "string"
},
"world_readable": {
"description": "Whether the room may be viewed by guest 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/unstable/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/unstable/push-gateway-api/#post_matrixpushv1notify).",
"properties": {
"format": {
"description": "The format to send notifications in to Push Gateways if the\n`kind` is `http`. The details about what fields the\nhomeserver should send to the push gateway are defined in the\n[Push Gateway Specification](https://spec.matrix.org/unstable/push-gateway-api/). Currently the only format\navailable is '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": {
Raw
synapse-admin.json
View raw

(Sorry about that, but we can’t show files that are this big right now.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment