From 02b81f10099dd6aa317d17bb8ab2736731338b37 Mon Sep 17 00:00:00 2001 From: Michael Telatynski <7t3chguy@gmail.com> Date: Tue, 8 Aug 2023 14:15:12 +0100 Subject: [PATCH] Fetch openapi spec for Matrix client-server API --- .eslintrc.js | 6 + package.json | 3 +- src/@types/matrix-client-server.d.ts | 18646 +++++++++++++++++++++++++ 3 files changed, 18654 insertions(+), 1 deletion(-) create mode 100644 src/@types/matrix-client-server.d.ts diff --git a/.eslintrc.js b/.eslintrc.js index e0150cca7d1..e42c9b8a551 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -125,5 +125,11 @@ module.exports = { "@typescript-eslint/explicit-member-accessibility": "off", }, }, + { + files: ["src/@types/matrix-client-server.d.ts"], + rules: { + "tsdoc/syntax": "off", + }, + }, ], }; diff --git a/package.json b/package.json index f2bc38b8e65..983cd5b943e 100644 --- a/package.json +++ b/package.json @@ -23,7 +23,8 @@ "lint:types": "tsc --noEmit", "test": "jest", "test:watch": "jest --watch", - "coverage": "yarn test --coverage" + "coverage": "yarn test --coverage", + "fetch-openapi": "openapi-typescript https://spec.matrix.org/latest/client-server-api/api.json --output src/@types/matrix-client-server.d.ts" }, "repository": { "type": "git", diff --git a/src/@types/matrix-client-server.d.ts b/src/@types/matrix-client-server.d.ts new file mode 100644 index 00000000000..5036fe8fd0a --- /dev/null +++ b/src/@types/matrix-client-server.d.ts @@ -0,0 +1,18646 @@ +/** + * This file was auto-generated by openapi-typescript. + * Do not make direct changes to the file. + */ + +export interface paths { + "/.well-known/matrix/client": { + /** + * Gets discovery information about the domain. The file may include + * additional keys, which MUST follow the Java package naming convention, + * e.g. `com.example.myapp.property`. This ensures property names are + * suitably namespaced for each application and reduces the risk of + * clashes. + * + * Note that this endpoint is not necessarily handled by the homeserver, + * but by another webserver, to be used for discovering the homeserver URL. + */ + get: operations["getWellknown"]; + }; + "/_matrix/client/v1/appservice/{appserviceId}/ping": { + /** + * This API asks the homeserver to call the + * [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the + * application service to ensure that the homeserver can communicate + * with the application service. + * + * This API requires the use of an application service access token (`as_token`) + * instead of a typical client's access token. This API cannot be invoked by + * users who are not identified as application services. Additionally, the + * appservice ID in the path must be the same as the appservice whose `as_token` + * is being used. + */ + post: operations["pingAppservice"]; + }; + "/_matrix/client/v1/login/get_token": { + /** + * Optional endpoint - the server is not required to implement this endpoint if it does not + * intend to use or support this functionality. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * An already-authenticated client can call this endpoint to generate a single-use, time-limited, + * token for an unauthenticated client to log in with, becoming logged in as the same user which + * called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + * login flow with the homeserver. + * + * Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + * this feature if the server is not offering it. Authenticated clients can check for support on + * a per-user basis with the `m.get_login_token` [capability](https://spec.matrix.org/v1.7/client-server-api/#capabilities-negotiation), + * while unauthenticated clients can detect server support by looking for an `m.login.token` login + * flow with `get_login_token: true` on [`GET /login`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3login). + * + * In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + * left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + * might standarise a way to transmit the token between clients. + * + * The generated token MUST only be valid for a single login, enforced by the server. Clients which + * intend to log in multiple devices must generate a token for each. + * + * With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + * for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + * the user for verification to ensure explicit consent is gained for each additional client. + * + * Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + * of 1 request per minute. + */ + post: operations["generateLoginToken"]; + }; + "/_matrix/client/v1/register/m.login.registration_token/validity": { + /** + * Queries the server to determine if a given registration token is still + * valid at the time of request. This is a point-in-time check where the + * token might still expire by the time it is used. + * + * Servers should be sure to rate limit this endpoint to avoid brute force + * attacks. + */ + get: operations["registrationTokenValidity"]; + }; + "/_matrix/client/v1/rooms/{roomId}/hierarchy": { + /** + * Paginates over the space tree in a depth-first manner to locate child rooms of a given space. + * + * Where a child room is unknown to the local server, federation is used to fill in the details. + * The servers listed in the `via` array should be contacted to attempt to fill in missing rooms. + * + * Only [`m.space.child`](#mspacechild) state events of the room are considered. Invalid child + * rooms and parent events are not covered by this endpoint. + */ + get: operations["getSpaceHierarchy"]; + }; + "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}": { + /** + * Retrieve all of the child events for a given parent event. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + get: operations["getRelatingEvents"]; + }; + "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}/{relType}": { + /** + * Retrieve all of the child events for a given parent event which relate to the parent + * using the given `relType`. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + get: operations["getRelatingEventsWithRelType"]; + }; + "/_matrix/client/v1/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}": { + /** + * Retrieve all of the child events for a given parent event which relate to the parent + * using the given `relType` and have the given `eventType`. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + get: operations["getRelatingEventsWithRelTypeAndEventType"]; + }; + "/_matrix/client/v1/rooms/{roomId}/threads": { + /** + * This API is used to paginate through the list of the thread roots in a given room. + * + * Optionally, the returned list may be filtered according to whether the requesting + * user has participated in the thread. + */ + get: operations["getThreadRoots"]; + }; + "/_matrix/client/v1/rooms/{roomId}/timestamp_to_event": { + /** + * Get the ID of the event closest to the given timestamp, in the + * direction specified by the `dir` parameter. + * + * If the server does not have all of the room history and does not have + * an event suitably close to the requested timestamp, it can use the + * corresponding [federation endpoint](https://spec.matrix.org/v1.7/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid) + * to ask other servers for a suitable event. + * + * After calling this endpoint, clients can call + * [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid) + * to obtain a pagination token to retrieve the events around the returned event. + * + * The event returned by this endpoint could be an event that the client + * cannot render, and so may need to paginate in order to locate an event + * that it can display, which may end up being outside of the client's + * suitable range. Clients can employ different strategies to display + * something reasonable to the user. For example, the client could try + * paginating in one direction for a while, while looking at the + * timestamps of the events that it is paginating through, and if it + * exceeds a certain difference from the target timestamp, it can try + * paginating in the opposite direction. The client could also simply + * paginate in one direction and inform the user that the closest event + * found in that direction is outside of the expected range. + */ + get: operations["getEventByTimestamp"]; + }; + "/_matrix/client/v3/account/3pid": { + /** + * Gets a list of the third-party identifiers that the homeserver has + * associated with the user's account. + * + * This is *not* the same as the list of third-party identifiers bound to + * the user's Matrix ID in identity servers. + * + * Identifiers in this list may be used by the homeserver as, for example, + * identifiers that it will accept to reset the user's account password. + */ + get: operations["getAccount3PIDs"]; + /** + * Adds contact information to the user's account. + * + * This endpoint is deprecated in favour of the more specific `/3pid/add` + * and `/3pid/bind` endpoints. + * + * **Note:** + * Previously this endpoint supported a `bind` parameter. This parameter + * has been removed, making this endpoint behave as though it was `false`. + * This results in this endpoint being an equivalent to `/3pid/bind` rather + * than dual-purpose. + */ + post: operations["post3PIDs"]; + }; + "/_matrix/client/v3/account/3pid/add": { + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Adds contact information to the user's account. Homeservers should use 3PIDs added + * through this endpoint for password resets instead of relying on the identity server. + * + * Homeservers should prevent the caller from adding a 3PID to their account if it has + * already been added to another user's account on the homeserver. + */ + post: operations["add3PID"]; + }; + "/_matrix/client/v3/account/3pid/bind": { + /** + * Binds a 3PID to the user's account through the specified identity server. + * + * Homeservers should not prevent this request from succeeding if another user + * has bound the 3PID. Homeservers should simply proxy any errors received by + * the identity server to the caller. + * + * Homeservers should track successful binds so they can be unbound later. + */ + post: operations["bind3PID"]; + }; + "/_matrix/client/v3/account/3pid/delete": { + /** + * Removes a third-party identifier from the user's account. This might not + * cause an unbind of the identifier from the identity server. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + post: operations["delete3pidFromAccount"]; + }; + "/_matrix/client/v3/account/3pid/email/requestToken": { + /** + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding an email address to an + * account. This API's parameters and response are identical to that of + * the [`/register/email/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint. The homeserver should validate + * the email itself, either by sending a validation email itself or by using + * a service it has control over. + */ + post: operations["requestTokenTo3PIDEmail"]; + }; + "/_matrix/client/v3/account/3pid/msisdn/requestToken": { + /** + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding a phone number to an + * account. This API's parameters and response are identical to that of + * the [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint. The homeserver should validate + * the phone number itself, either by sending a validation message itself or by using + * a service it has control over. + */ + post: operations["requestTokenTo3PIDMSISDN"]; + }; + "/_matrix/client/v3/account/3pid/unbind": { + /** + * Removes a user's third-party identifier from the provided identity server + * without removing it from the homeserver. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + post: operations["unbind3pidFromAccount"]; + }; + "/_matrix/client/v3/account/deactivate": { + /** + * Deactivate the user's account, removing all ability for the user to + * login again. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + post: operations["deactivateAccount"]; + }; + "/_matrix/client/v3/account/password": { + /** + * Changes the password for an account on this homeserver. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api) to + * ensure the user changing the password is actually the owner of the + * account. + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. The homeserver SHOULD NOT revoke the + * access token provided in the request. Whether other access tokens for + * the user are revoked depends on the request parameters. + */ + post: operations["changePassword"]; + }; + "/_matrix/client/v3/account/password/email/requestToken": { + /** + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/email/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given email address could be found. The server may instead send an + * email to the given address prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + */ + post: operations["requestTokenToResetPasswordEmail"]; + }; + "/_matrix/client/v3/account/password/msisdn/requestToken": { + /** + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the phone number itself, either by sending a + * validation message itself or by using a service it has control over. + */ + post: operations["requestTokenToResetPasswordMSISDN"]; + }; + "/_matrix/client/v3/account/whoami": { + /** + * Gets information about the owner of a given access token. + * + * Note that, as with the rest of the Client-Server API, + * Application Services may masquerade as users within their + * namespace by giving a `user_id` query parameter. In this + * situation, the server should verify that the given `user_id` + * is registered by the appservice, and return it in the response + * body. + */ + get: operations["getTokenOwner"]; + }; + "/_matrix/client/v3/admin/whois/{userId}": { + /** + * Gets information about a particular user. + * + * This API may be restricted to only be called by the user being looked + * up, or by a server admin. Server-local administrator privileges are not + * specified in this document. + */ + get: operations["getWhoIs"]; + }; + "/_matrix/client/v3/capabilities": { + /** + * Gets information about the server's supported feature set + * and other relevant capabilities. + */ + get: operations["getCapabilities"]; + }; + "/_matrix/client/v3/createRoom": { + /** + * Create a new room with various configuration options. + * + * The server MUST apply the normal state resolution rules when creating + * the new room, including checking power levels for each event. It MUST + * apply the events implied by the request in the following order: + * + * 1. The `m.room.create` event itself. Must be the first event in the + * room. + * + * 2. An `m.room.member` event for the creator to join the room. This is + * needed so the remaining events can be sent. + * + * 3. A default `m.room.power_levels` event, giving the room creator + * (and not other members) permission to send state events. Overridden + * by the `power_level_content_override` parameter. + * + * 4. An `m.room.canonical_alias` event if `room_alias_name` is given. + * + * 5. Events set by the `preset`. Currently these are the `m.room.join_rules`, + * `m.room.history_visibility`, and `m.room.guest_access` state events. + * + * 6. Events listed in `initial_state`, in the order that they are + * listed. + * + * 7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` + * state events). + * + * 8. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + * `membership: invite` and `m.room.third_party_invite`). + * + * The available presets do the following with respect to room state: + * + * | Preset | `join_rules` | `history_visibility` | `guest_access` | Other | + * |------------------------|--------------|----------------------|----------------|-------| + * | `private_chat` | `invite` | `shared` | `can_join` | | + * | `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. | + * | `public_chat` | `public` | `shared` | `forbidden` | | + * + * The server will create a `m.room.create` event in the room with the + * requesting user as the creator, alongside other keys provided in the + * `creation_content`. + */ + post: operations["createRoom"]; + }; + "/_matrix/client/v3/delete_devices": { + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Deletes the given devices, and invalidates any access token associated with them. + */ + post: operations["deleteDevices"]; + }; + "/_matrix/client/v3/devices": { + /** Gets information about all devices for the current user. */ + get: operations["getDevices"]; + }; + "/_matrix/client/v3/devices/{deviceId}": { + /** Gets information on a single device, by device id. */ + get: operations["getDevice"]; + /** Updates the metadata on the given device. */ + put: operations["updateDevice"]; + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Deletes the given device, and invalidates any access token associated with it. + */ + delete: operations["deleteDevice"]; + }; + "/_matrix/client/v3/directory/list/appservice/{networkId}/{roomId}": { + /** + * Updates the visibility of a given room on the application service's room + * directory. + * + * This API is similar to the room directory visibility API used by clients + * to update the homeserver's more general room directory. + * + * This API requires the use of an application service access token (`as_token`) + * instead of a typical client's access_token. This API cannot be invoked by + * users who are not identified as application services. + */ + put: operations["updateAppserviceRoomDirectoryVisibility"]; + }; + "/_matrix/client/v3/directory/list/room/{roomId}": { + /** Gets the visibility of a given room on the server's public room directory. */ + get: operations["getRoomVisibilityOnDirectory"]; + /** + * Sets the visibility of a given room in the server's public room + * directory. + * + * Servers may choose to implement additional access control checks + * here, for instance that room visibility can only be changed by + * the room creator or a server administrator. + */ + put: operations["setRoomVisibilityOnDirectory"]; + }; + "/_matrix/client/v3/directory/room/{roomAlias}": { + /** + * Requests that the server resolve a room alias to a room ID. + * + * The server will use the federation API to resolve the alias if the + * domain part of the alias does not correspond to the server's own + * domain. + */ + get: operations["getRoomIdByAlias"]; + put: operations["setRoomAlias"]; + /** + * Remove a mapping of room alias to room ID. + * + * Servers may choose to implement additional access control checks here, for instance that + * room aliases can only be deleted by their creator or a server administrator. + * + * **Note:** + * Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias` + * state event in the room when an alias is removed. Servers which choose to update the + * canonical alias event are recommended to, in addition to their other relevant permission + * checks, delete the alias and return a successful response even if the user does not + * have permission to update the `m.room.canonical_alias` event. + */ + delete: operations["deleteRoomAlias"]; + }; + "/_matrix/client/v3/events": { + /** + * This will listen for new events and return them to the caller. This will + * block until an event is received, or until the `timeout` is reached. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) + * endpoint with a `since` parameter. See + * the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + get: operations["getEvents"]; + }; + "/_matrix/client/v3/events ": { + /** + * This will listen for new events related to a particular room and return + * them to the caller. This will block until an event is received, or until + * the `timeout` is reached. + * + * This API is the same as the normal `/events` endpoint, but can be + * called by users who have not joined the room. + * + * Note that the normal `/events` endpoint has been deprecated. This + * API will also be deprecated at some point, but its replacement is not + * yet known. + */ + get: operations["peekEvents"]; + }; + "/_matrix/client/v3/events/{eventId}": { + /** + * Get a single event based on `event_id`. You must have permission to + * retrieve this event e.g. by being a member in the room for this event. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the + * [/rooms/{roomId}/event/{eventId}](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomideventeventid) API + * or the [/rooms/{roomId}/context/{eventId](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API. + */ + get: operations["getOneEvent"]; + }; + "/_matrix/client/v3/initialSync": { + /** + * This returns the full state for this user, with an optional limit on the + * number of messages per room to return. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) + * endpoint with no `since` parameter. See + * the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + get: operations["initialSync"]; + }; + "/_matrix/client/v3/join/{roomIdOrAlias}": { + /** + * *Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`. + * + * This API starts a user participating in a particular room, if that user + * is allowed to participate in that room. After this call, the client is + * allowed to see all current state events in the room, and all subsequent + * events associated with the room until the user leaves the room. + * + * After a user has joined a room, the room will appear as an entry in the + * response of the [`/initialSync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3initialsync) + * and [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) APIs. + */ + post: operations["joinRoom"]; + }; + "/_matrix/client/v3/joined_rooms": { + /** This API returns a list of the user's current rooms. */ + get: operations["getJoinedRooms"]; + }; + "/_matrix/client/v3/keys/changes": { + /** + * Gets a list of users who have updated their device identity keys since a + * previous sync token. + * + * The server should include in the results any users who: + * + * * currently share a room with the calling user (ie, both users have + * membership state `join`); *and* + * * added new device identity keys or removed an existing device with + * identity keys, between `from` and `to`. + */ + get: operations["getKeysChanges"]; + }; + "/_matrix/client/v3/keys/claim": { + /** Claims one-time keys for use in pre-key messages. */ + post: operations["claimKeys"]; + }; + "/_matrix/client/v3/keys/device_signing/upload": { + /** + * Publishes cross-signing keys for the user. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + */ + post: operations["uploadCrossSigningKeys"]; + }; + "/_matrix/client/v3/keys/query": { + /** Returns the current devices and identity keys for the given users. */ + post: operations["queryKeys"]; + }; + "/_matrix/client/v3/keys/signatures/upload": { + /** + * Publishes cross-signing signatures for the user. + * + * The request body is a map from user ID to key ID to signed JSON object. + * The signed JSON object must match the key previously uploaded or + * retrieved for the given key ID, with the exception of the `signatures` + * property, which contains the new signature(s) to add. + */ + post: operations["uploadCrossSigningSignatures"]; + }; + "/_matrix/client/v3/keys/upload": { + /** Publishes end-to-end encryption keys for the device. */ + post: operations["uploadKeys"]; + }; + "/_matrix/client/v3/knock/{roomIdOrAlias}": { + /** + * *Note that this API takes either a room ID or alias, unlike other membership APIs.* + * + * This API "knocks" on the room to ask for permission to join, if the user + * is allowed to knock on the room. Acceptance of the knock happens out of + * band from this API, meaning that the client will have to watch for updates + * regarding the acceptance/rejection of the knock. + * + * If the room history settings allow, the user will still be able to see + * history of the room while being in the "knock" state. The user will have + * to accept the invitation to join the room (acceptance of knock) to see + * messages reliably. See the `/join` endpoints for more information about + * history visibility to the user. + * + * The knock will appear as an entry in the response of the + * [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) API. + */ + post: operations["knockRoom"]; + }; + "/_matrix/client/v3/login": { + /** + * Gets the homeserver's supported login types to authenticate users. Clients + * should pick one of these and supply it as the `type` when logging in. + */ + get: operations["getLoginFlows"]; + /** + * Authenticates the user, and issues an access token they can + * use to authorize themself in subsequent requests. + * + * If the client does not supply a `device_id`, the server must + * auto-generate one. + * + * The returned access token must be associated with the `device_id` + * supplied by the client or generated by the server. The server may + * invalidate any access token previously associated with that device. See + * [Relationship between access tokens and devices](https://spec.matrix.org/v1.7/client-server-api/#relationship-between-access-tokens-and-devices). + */ + post: operations["login"]; + }; + "/_matrix/client/v3/login/sso/redirect": { + /** + * A web-based Matrix client should instruct the user's browser to + * navigate to this endpoint in order to log in via SSO. + * + * The server MUST respond with an HTTP redirect to the SSO interface, + * or present a page which lets the user select an IdP to continue + * with in the event multiple are supported by the server. + */ + get: operations["redirectToSSO"]; + }; + "/_matrix/client/v3/login/sso/redirect/{idpId}": { + /** + * This endpoint is the same as `/login/sso/redirect`, though with an + * IdP ID from the original `identity_providers` array to inform the + * server of which IdP the client/user would like to continue with. + * + * The server MUST respond with an HTTP redirect to the SSO interface + * for that IdP. + */ + get: operations["redirectToIdP"]; + }; + "/_matrix/client/v3/logout": { + /** + * Invalidates an existing access token, so that it can no longer be used for + * authorization. The device associated with the access token is also deleted. + * [Device keys](https://spec.matrix.org/v1.7/client-server-api/#device-keys) for the device are deleted alongside the device. + */ + post: operations["logout"]; + }; + "/_matrix/client/v3/logout/all": { + /** + * Invalidates all access tokens for a user, so that they can no longer be used for + * authorization. This includes the access token that made this request. All devices + * for the user are also deleted. [Device keys](https://spec.matrix.org/v1.7/client-server-api/#device-keys) for the device are + * deleted alongside the device. + * + * This endpoint does not use the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api) because + * User-Interactive Authentication is designed to protect against attacks where the + * someone gets hold of a single access token then takes over the account. This + * endpoint invalidates all access tokens for the user, including the token used in + * the request, and therefore the attacker is unable to take over the account in + * this way. + */ + post: operations["logout_all"]; + }; + "/_matrix/client/v3/notifications": { + /** + * This API is used to paginate through the list of events that the + * user has been, or would have been notified about. + */ + get: operations["getNotifications"]; + }; + "/_matrix/client/v3/presence/{userId}/status": { + /** Get the given user's presence state. */ + get: operations["getPresence"]; + /** + * This API sets the given user's presence state. When setting the status, + * the activity time is updated to reflect that activity; the client does + * not need to specify the `last_active_ago` field. You cannot set the + * presence state of another user. + */ + put: operations["setPresence"]; + }; + "/_matrix/client/v3/profile/{userId}": { + /** + * Get the combined profile information for this user. This API may be used + * to fetch the user's own profile information or other users; either + * locally or on remote homeservers. This API may return keys which are not + * limited to `displayname` or `avatar_url`. + */ + get: operations["getUserProfile"]; + }; + "/_matrix/client/v3/profile/{userId}/avatar_url": { + /** + * Get the user's avatar URL. This API may be used to fetch the user's + * own avatar URL or to query the URL of other users; either locally or + * on remote homeservers. + */ + get: operations["getAvatarUrl"]; + /** + * This API sets the given user's avatar URL. You must have permission to + * set this user's avatar URL, e.g. you need to have their `access_token`. + */ + put: operations["setAvatarUrl"]; + }; + "/_matrix/client/v3/profile/{userId}/displayname": { + /** + * Get the user's display name. This API may be used to fetch the user's + * own displayname or to query the name of other users; either locally or + * on remote homeservers. + */ + get: operations["getDisplayName"]; + /** + * This API sets the given user's display name. You must have permission to + * set this user's display name, e.g. you need to have their `access_token`. + */ + put: operations["setDisplayName"]; + }; + "/_matrix/client/v3/publicRooms": { + /** + * Lists the public rooms on the server. + * + * This API returns paginated responses. The rooms are ordered by the number + * of joined members, with the largest rooms first. + */ + get: operations["getPublicRooms"]; + /** + * Lists the public rooms on the server, with optional filter. + * + * This API returns paginated responses. The rooms are ordered by the number + * of joined members, with the largest rooms first. + */ + post: operations["queryPublicRooms"]; + }; + "/_matrix/client/v3/pushers": { + /** Gets all currently active pushers for the authenticated user. */ + get: operations["getPushers"]; + }; + "/_matrix/client/v3/pushers/set": { + /** + * This endpoint allows the creation, modification and deletion of [pushers](https://spec.matrix.org/v1.7/client-server-api/#push-notifications) + * for this user ID. The behaviour of this endpoint varies depending on the + * values in the JSON body. + * + * If `kind` is not `null`, the pusher with this `app_id` and `pushkey` + * for this user is updated, or it is created if it doesn't exist. If + * `kind` is `null`, the pusher with this `app_id` and `pushkey` for this + * user is deleted. + */ + post: operations["postPusher"]; + }; + "/_matrix/client/v3/pushrules/": { + /** + * Retrieve all push rulesets for this user. Clients can "drill-down" on + * the rulesets by suffixing a `scope` to this path e.g. + * `/pushrules/global/`. This will return a subset of this data under the + * specified key e.g. the `global` key. + */ + get: operations["getPushRules"]; + }; + "/_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}": { + /** Retrieve a single specified push rule. */ + get: operations["getPushRule"]; + /** + * This endpoint allows the creation and modification of user defined push + * rules. + * + * If a rule with the same `rule_id` already exists among rules of the same + * kind, it is updated with the new parameters, otherwise a new rule is + * created. + * + * If both `after` and `before` are provided, the new or updated rule must + * be the next most important rule with respect to the rule identified by + * `before`. + * + * If neither `after` nor `before` are provided and the rule is created, it + * should be added as the most important user defined rule among rules of + * the same kind. + * + * When creating push rules, they MUST be enabled by default. + */ + put: operations["setPushRule"]; + /** This endpoint removes the push rule defined in the path. */ + delete: operations["deletePushRule"]; + }; + "/_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}/actions": { + /** This endpoint get the actions for the specified push rule. */ + get: operations["getPushRuleActions"]; + /** + * This endpoint allows clients to change the actions of a push rule. + * This can be used to change the actions of builtin rules. + */ + put: operations["setPushRuleActions"]; + }; + "/_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}/enabled": { + /** This endpoint gets whether the specified push rule is enabled. */ + get: operations["isPushRuleEnabled"]; + /** This endpoint allows clients to enable or disable the specified push rule. */ + put: operations["setPushRuleEnabled"]; + }; + "/_matrix/client/v3/refresh": { + /** + * Refresh an access token. Clients should use the returned access token + * when making subsequent API calls, and store the returned refresh token + * (if given) in order to refresh the new access token when necessary. + * + * After an access token has been refreshed, a server can choose to + * invalidate the old access token immediately, or can choose not to, for + * example if the access token would expire soon anyways. Clients should + * not make any assumptions about the old access token still being valid, + * and should use the newly provided access token instead. + * + * The old refresh token remains valid until the new access token or refresh token + * is used, at which point the old refresh token is revoked. + * + * Note that this endpoint does not require authentication via an + * access token. Authentication is provided via the refresh token. + * + * Application Service identity assertion is disabled for this endpoint. + */ + post: operations["refresh"]; + }; + "/_matrix/client/v3/register": { + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api), except in + * the cases where a guest account is being registered. + * + * Register for an account on this homeserver. + * + * There are two kinds of user account: + * + * - `user` accounts. These accounts may use the full API described in this specification. + * + * - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. + * + * If registration is successful, this endpoint will issue an access token + * the client can use to authorize itself in subsequent requests. + * + * If the client does not supply a `device_id`, the server must + * auto-generate one. + * + * The server SHOULD register an account with a User ID based on the + * `username` provided, if any. Note that the grammar of Matrix User ID + * localparts is restricted, so the server MUST either map the provided + * `username` onto a `user_id` in a logical manner, or reject any + * `username` which does not comply to the grammar with + * `M_INVALID_USERNAME`. + * + * Matrix clients MUST NOT assume that localpart of the registered + * `user_id` matches the provided `username`. + * + * The returned access token must be associated with the `device_id` + * supplied by the client or generated by the server. The server may + * invalidate any access token previously associated with that device. See + * [Relationship between access tokens and devices](https://spec.matrix.org/v1.7/client-server-api/#relationship-between-access-tokens-and-devices). + * + * When registering a guest account, all parameters in the request body + * with the exception of `initial_device_display_name` MUST BE ignored + * by the server. The server MUST pick a `device_id` for the account + * regardless of input. + * + * Any user ID returned by this API must conform to the grammar given in the + * [Matrix specification](https://spec.matrix.org/v1.7/appendices/#user-identifiers). + */ + post: operations["register"]; + }; + "/_matrix/client/v3/register/available": { + /** + * Checks to see if a username is available, and valid, for the server. + * + * The server should check to ensure that, at the time of the request, the + * username requested is available for use. This includes verifying that an + * application service has not claimed the username and that the username + * fits the server's desired requirements (for example, a server could dictate + * that it does not permit usernames with underscores). + * + * Matrix clients may wish to use this API prior to attempting registration, + * however the clients must also be aware that using this API does not normally + * reserve the username. This can mean that the username becomes unavailable + * between checking its availability and attempting to register it. + */ + get: operations["checkUsernameAvailability"]; + }; + "/_matrix/client/v3/register/email/requestToken": { + /** + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. + */ + post: operations["requestTokenToRegisterEmail"]; + }; + "/_matrix/client/v3/register/msisdn/requestToken": { + /** + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. + */ + post: operations["requestTokenToRegisterMSISDN"]; + }; + "/_matrix/client/v3/room_keys/keys": { + /** Retrieve the keys from the backup. */ + get: operations["getRoomKeys"]; + /** Store several keys in the backup. */ + put: operations["putRoomKeys"]; + /** Delete the keys from the backup. */ + delete: operations["deleteRoomKeys"]; + }; + "/_matrix/client/v3/room_keys/keys/{roomId}": { + /** Retrieve the keys from the backup for a given room. */ + get: operations["getRoomKeysByRoomId"]; + /** Store several keys in the backup for a given room. */ + put: operations["putRoomKeysByRoomId"]; + /** Delete the keys from the backup for a given room. */ + delete: operations["deleteRoomKeysByRoomId"]; + }; + "/_matrix/client/v3/room_keys/keys/{roomId}/{sessionId}": { + /** Retrieve a key from the backup. */ + get: operations["getRoomKeyBySessionId"]; + /** Store a key in the backup. */ + put: operations["putRoomKeyBySessionId"]; + /** Delete a key from the backup. */ + delete: operations["deleteRoomKeyBySessionId"]; + }; + "/_matrix/client/v3/room_keys/version": { + /** Get information about the latest backup version. */ + get: operations["getRoomKeysVersionCurrent"]; + /** Creates a new backup. */ + post: operations["postRoomKeysVersion"]; + }; + "/_matrix/client/v3/room_keys/version/{version}": { + /** Get information about an existing backup. */ + get: operations["getRoomKeysVersion"]; + /** Update information about an existing backup. Only `auth_data` can be modified. */ + put: operations["putRoomKeysVersion"]; + /** + * Delete an existing key backup. Both the information about the backup, + * as well as all key data related to the backup will be deleted. + */ + delete: operations["deleteRoomKeysVersion"]; + }; + "/_matrix/client/v3/rooms/{roomId}/aliases": { + /** + * Get a list of aliases maintained by the local server for the + * given room. + * + * This endpoint can be called by users who are in the room (external + * users receive an `M_FORBIDDEN` error response). If the room's + * `m.room.history_visibility` maps to `world_readable`, any + * user can call this endpoint. + * + * Servers may choose to implement additional access control checks here, + * such as allowing server administrators to view aliases regardless of + * membership. + * + * **Note:** + * Clients are recommended not to display this list of aliases prominently + * as they are not curated, unlike those listed in the `m.room.canonical_alias` + * state event. + */ + get: operations["getLocalAliases"]; + }; + "/_matrix/client/v3/rooms/{roomId}/ban": { + /** + * Ban a user in the room. If the user is currently in the room, also kick them. + * + * When a user is banned from a room, they may not join it or be invited to it until they are unbanned. + * + * The caller must have the required power level in order to perform this operation. + */ + post: operations["ban"]; + }; + "/_matrix/client/v3/rooms/{roomId}/context/{eventId}": { + /** + * This API returns a number of events that happened just before and + * after the specified event. This allows clients to get the context + * surrounding an event. + * + * *Note*: This endpoint supports lazy-loading of room member events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) for more information. + */ + get: operations["getEventContext"]; + }; + "/_matrix/client/v3/rooms/{roomId}/event/{eventId}": { + /** + * Get a single event based on `roomId/eventId`. You must have permission to + * retrieve this event e.g. by being a member in the room for this event. + */ + get: operations["getOneRoomEvent"]; + }; + "/_matrix/client/v3/rooms/{roomId}/forget": { + /** + * This API stops a user remembering about a particular room. + * + * In general, history is a first class citizen in Matrix. After this API + * is called, however, a user will no longer be able to retrieve history + * for this room. If all users on a homeserver forget a room, the room is + * eligible for deletion from that homeserver. + * + * If the user is currently joined to the room, they must leave the room + * before calling this API. + */ + post: operations["forgetRoom"]; + }; + "/_matrix/client/v3/rooms/{roomId}/initialSync": { + /** + * Get a copy of the current state and the most recent messages in a room. + * + * This endpoint was deprecated in r0 of this specification. There is no + * direct replacement; the relevant information is returned by the + * [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) API. See the + * [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + get: operations["roomInitialSync"]; + }; + "/_matrix/client/v3/rooms/{roomId}/invite": { + /** + * *Note that there are two forms of this API, which are documented separately. + * This version of the API does not require that the inviter know the Matrix + * identifier of the invitee, and instead relies on third-party identifiers. + * The homeserver uses an identity server to perform the mapping from + * third-party identifier to a Matrix identifier. The other is documented in the* + * [joining rooms section](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3roomsroomidinvite). + * + * This API invites a user to participate in a particular room. + * They do not start participating in the room until they actually join the + * room. + * + * Only users currently in a particular room can invite other users to + * join that room. + * + * If the identity server did know the Matrix user identifier for the + * third-party identifier, the homeserver will append a `m.room.member` + * event to the room. + * + * If the identity server does not know a Matrix user identifier for the + * passed third-party identifier, the homeserver will issue an invitation + * which can be accepted upon providing proof of ownership of the third- + * party identifier. This is achieved by the identity server generating a + * token, which it gives to the inviting homeserver. The homeserver will + * add an `m.room.third_party_invite` event into the graph for the room, + * containing that token. + * + * When the invitee binds the invited third-party identifier to a Matrix + * user ID, the identity server will give the user a list of pending + * invitations, each containing: + * + * - The room ID to which they were invited + * + * - The token given to the homeserver + * + * - A signature of the token, signed with the identity server's private key + * + * - The matrix user ID who invited them to the room + * + * If a token is requested from the identity server, the homeserver will + * append a `m.room.third_party_invite` event to the room. + */ + post: operations["inviteBy3PID"]; + }; + "/_matrix/client/v3/rooms/{roomId}/invite ": { + /** + * *Note that there are two forms of this API, which are documented separately. + * This version of the API requires that the inviter knows the Matrix + * identifier of the invitee. The other is documented in the + * [third-party invites](https://spec.matrix.org/v1.7/client-server-api/#third-party-invites) section.* + * + * This API invites a user to participate in a particular room. + * They do not start participating in the room until they actually join the + * room. + * + * Only users currently in a particular room can invite other users to + * join that room. + * + * If the user was invited to the room, the homeserver will append a + * `m.room.member` event to the room. + */ + post: operations["inviteUser"]; + }; + "/_matrix/client/v3/rooms/{roomId}/join": { + /** + * *Note that this API requires a room ID, not alias.* + * `/join/{roomIdOrAlias}` *exists if you have a room alias.* + * + * This API starts a user participating in a particular room, if that user + * is allowed to participate in that room. After this call, the client is + * allowed to see all current state events in the room, and all subsequent + * events associated with the room until the user leaves the room. + * + * After a user has joined a room, the room will appear as an entry in the + * response of the [`/initialSync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3initialsync) + * and [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) APIs. + */ + post: operations["joinRoomById"]; + }; + "/_matrix/client/v3/rooms/{roomId}/joined_members": { + /** This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. */ + get: operations["getJoinedMembersByRoom"]; + }; + "/_matrix/client/v3/rooms/{roomId}/kick": { + /** + * Kick a user from the room. + * + * The caller must have the required power level in order to perform this operation. + * + * Kicking a user adjusts the target member's membership state to be `leave` with an + * optional `reason`. Like with other membership changes, a user can directly adjust + * the target member's state by making a request to `/rooms//state/m.room.member/`. + */ + post: operations["kick"]; + }; + "/_matrix/client/v3/rooms/{roomId}/leave": { + /** + * This API stops a user participating in a particular room. + * + * If the user was already in the room, they will no longer be able to see + * new events in the room. If the room requires an invite to join, they + * will need to be re-invited before they can re-join. + * + * If the user was invited to the room, but had not joined, this call + * serves to reject the invite. + * + * The user will still be allowed to retrieve history from the room which + * they were previously allowed to see. + */ + post: operations["leaveRoom"]; + }; + "/_matrix/client/v3/rooms/{roomId}/members": { + /** Get the list of members for this room. */ + get: operations["getMembersByRoom"]; + }; + "/_matrix/client/v3/rooms/{roomId}/messages": { + /** + * This API returns a list of message and state events for a room. It uses + * pagination query parameters to paginate history in the room. + * + * *Note*: This endpoint supports lazy-loading of room member events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) for more information. + */ + get: operations["getRoomEvents"]; + }; + "/_matrix/client/v3/rooms/{roomId}/read_markers": { + /** + * Sets the position of the read marker for a given room, and optionally + * the read receipt's location. + */ + post: operations["setReadMarker"]; + }; + "/_matrix/client/v3/rooms/{roomId}/receipt/{receiptType}/{eventId}": { + /** + * This API updates the marker for the given receipt type to the event ID + * specified. + */ + post: operations["postReceipt"]; + }; + "/_matrix/client/v3/rooms/{roomId}/redact/{eventId}/{txnId}": { + /** + * Strips all information out of an event which isn't critical to the + * integrity of the server-side representation of the room. + * + * This cannot be undone. + * + * Any user with a power level greater than or equal to the `m.room.redaction` + * event power level may send redaction events in the room. If the user's power + * level greater is also greater than or equal to the `redact` power level + * of the room, the user may redact events sent by other users. + * + * Server administrators may redact events sent by users on their server. + */ + put: operations["redactEvent"]; + }; + "/_matrix/client/v3/rooms/{roomId}/report/{eventId}": { + /** + * Reports an event as inappropriate to the server, which may then notify + * the appropriate people. + */ + post: operations["reportContent"]; + }; + "/_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}": { + /** + * This endpoint is used to send a message event to a room. Message events + * allow access to historical events and pagination, making them suited + * for "once-off" activity in a room. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * [Room Events](https://spec.matrix.org/v1.7/client-server-api/#room-events) for the m. event specification. + */ + put: operations["sendMessage"]; + }; + "/_matrix/client/v3/rooms/{roomId}/state": { + /** Get the state events for the current state of a room. */ + get: operations["getRoomState"]; + }; + "/_matrix/client/v3/rooms/{roomId}/state/{eventType}/{stateKey}": { + /** + * Looks up the contents of a state event in a room. If the user is + * joined to the room then the state is taken from the current + * state of the room. If the user has left the room then the state is + * taken from the state of the room when they left. + */ + get: operations["getRoomStateWithKey"]; + /** + * State events can be sent using this endpoint. These events will be + * overwritten if ``, `` and `` all + * match. + * + * Requests to this endpoint **cannot use transaction IDs** + * like other `PUT` paths because they cannot be differentiated from the + * `state_key`. Furthermore, `POST` is unsupported on state paths. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * [Room Events](https://spec.matrix.org/v1.7/client-server-api/#room-events) for the `m.` event specification. + * + * If the event type being sent is `m.room.canonical_alias` servers + * SHOULD ensure that any new aliases being listed in the event are valid + * per their grammar/syntax and that they point to the room ID where the + * state event is to be sent. Servers do not validate aliases which are + * being removed or are already present in the state event. + */ + put: operations["setRoomStateWithKey"]; + }; + "/_matrix/client/v3/rooms/{roomId}/typing/{userId}": { + /** + * This tells the server that the user is typing for the next N + * milliseconds where N is the value specified in the `timeout` key. + * Alternatively, if `typing` is `false`, it tells the server that the + * user has stopped typing. + */ + put: operations["setTyping"]; + }; + "/_matrix/client/v3/rooms/{roomId}/unban": { + /** + * Unban a user from the room. This allows them to be invited to the room, + * and join if they would otherwise be allowed to join according to its join rules. + * + * The caller must have the required power level in order to perform this operation. + */ + post: operations["unban"]; + }; + "/_matrix/client/v3/rooms/{roomId}/upgrade": { + /** Upgrades the given room to a particular room version. */ + post: operations["upgradeRoom"]; + }; + "/_matrix/client/v3/search": { + /** Performs a full text search across different categories. */ + post: operations["search"]; + }; + "/_matrix/client/v3/sendToDevice/{eventType}/{txnId}": { + /** + * This endpoint is used to send send-to-device events to a set of + * client devices. + */ + put: operations["sendToDevice"]; + }; + "/_matrix/client/v3/sync": { + /** + * Synchronise the client's state with the latest state on the server. + * Clients use this API when they first log in to get an initial snapshot + * of the state on the server, and then continue to call this API to get + * incremental deltas to the state, and to receive new messages. + * + * *Note*: This endpoint supports lazy-loading. See [Filtering](https://spec.matrix.org/v1.7/client-server-api/#filtering) + * for more information. Lazy-loading members is only supported on a `StateFilter` + * for this endpoint. When lazy-loading is enabled, servers MUST include the + * syncing user's own membership event when they join a room, or when the + * full state of rooms is requested, to aid discovering the user's avatar & + * displayname. + * + * Further, like other members, the user's own membership event is eligible + * for being considered redundant by the server. When a sync is `limited`, + * the server MUST return membership events for events in the gap + * (between `since` and the start of the returned timeline), regardless + * as to whether or not they are redundant. This ensures that joins/leaves + * and profile changes which occur during the gap are not lost. + * + * Note that the default behaviour of `state` is to include all membership + * events, alongside other state, when lazy-loading is not enabled. + */ + get: operations["sync"]; + }; + "/_matrix/client/v3/thirdparty/location": { + /** + * Retrieve an array of third-party network locations from a Matrix room + * alias. + */ + get: operations["queryLocationByAlias"]; + }; + "/_matrix/client/v3/thirdparty/location/{protocol}": { + /** + * Requesting this endpoint with a valid protocol name results in a list + * of successful mapping results in a JSON array. Each result contains + * objects to represent the Matrix room or rooms that represent a portal + * to this third-party network. Each has the Matrix room alias string, + * an identifier for the particular third-party network protocol, and an + * object containing the network-specific fields that comprise this + * identifier. It should attempt to canonicalise the identifier as much + * as reasonably possible given the network type. + */ + get: operations["queryLocationByProtocol"]; + }; + "/_matrix/client/v3/thirdparty/protocol/{protocol}": { + /** Fetches the metadata from the homeserver about a particular third-party protocol. */ + get: operations["getProtocolMetadata"]; + }; + "/_matrix/client/v3/thirdparty/protocols": { + /** + * Fetches the overall metadata about protocols supported by the + * homeserver. Includes both the available protocols and all fields + * required for queries against each protocol. + */ + get: operations["getProtocols"]; + }; + "/_matrix/client/v3/thirdparty/user": { + /** Retrieve an array of third-party users from a Matrix User ID. */ + get: operations["queryUserByID"]; + }; + "/_matrix/client/v3/thirdparty/user/{protocol}": { + /** + * Retrieve a Matrix User ID linked to a user on the third-party service, given + * a set of user parameters. + */ + get: operations["queryUserByProtocol"]; + }; + "/_matrix/client/v3/user/{userId}/account_data/{type}": { + /** + * Get some account data for the client. This config is only visible to the user + * that set the account data. + */ + get: operations["getAccountData"]; + /** + * Set some account data for the client. This config is only visible to the user + * that set the account data. The config will be available to clients through the + * top-level `account_data` field in the homeserver response to + * [/sync](#get_matrixclientv3sync). + */ + put: operations["setAccountData"]; + }; + "/_matrix/client/v3/user/{userId}/filter": { + /** + * Uploads a new filter definition to the homeserver. + * Returns a filter ID that may be used in future requests to + * restrict which events are returned to the client. + */ + post: operations["defineFilter"]; + }; + "/_matrix/client/v3/user/{userId}/filter/{filterId}": { + get: operations["getFilter"]; + }; + "/_matrix/client/v3/user/{userId}/openid/request_token": { + /** + * Gets an OpenID token object that the requester may supply to another + * service to verify their identity in Matrix. The generated token is only + * valid for exchanging for user information from the federation API for + * OpenID. + * + * The access token generated is only valid for the OpenID API. It cannot + * be used to request another OpenID access token or call `/sync`, for + * example. + */ + post: operations["requestOpenIdToken"]; + }; + "/_matrix/client/v3/user/{userId}/rooms/{roomId}/account_data/{type}": { + /** + * Get some account data for the client on a given room. This config is only + * visible to the user that set the account data. + */ + get: operations["getAccountDataPerRoom"]; + /** + * Set some account data for the client on a given room. This config is only + * visible to the user that set the account data. The config will be delivered to + * clients in the per-room entries via [/sync](#get_matrixclientv3sync). + */ + put: operations["setAccountDataPerRoom"]; + }; + "/_matrix/client/v3/user/{userId}/rooms/{roomId}/tags": { + /** List the tags set by a user on a room. */ + get: operations["getRoomTags"]; + }; + "/_matrix/client/v3/user/{userId}/rooms/{roomId}/tags/{tag}": { + /** Add a tag to the room. */ + put: operations["setRoomTag"]; + /** Remove a tag from the room. */ + delete: operations["deleteRoomTag"]; + }; + "/_matrix/client/v3/user_directory/search": { + /** + * Performs a search for users. The homeserver may + * determine which subset of users are searched, however the homeserver + * MUST at a minimum consider the users the requesting user shares a + * room with and those who reside in public rooms (known to the homeserver). + * The search MUST consider local users to the homeserver, and SHOULD + * query remote users as part of the search. + * + * The search is performed case-insensitively on user IDs and display + * names preferably using a collation determined based upon the + * `Accept-Language` header provided in the request, if present. + */ + post: operations["searchUserDirectory"]; + }; + "/_matrix/client/v3/voip/turnServer": { + /** + * This API provides credentials for the client to use when initiating + * calls. + */ + get: operations["getTurnServer"]; + }; + "/_matrix/client/versions": { + /** + * Gets the versions of the specification supported by the server. + * + * Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See + * [the Specification Versioning](../#specification-versions) for more + * information. + * + * The server may additionally advertise experimental features it supports + * through `unstable_features`. These features should be namespaced and + * may optionally include version information within their name if desired. + * Features listed here are not for optionally toggling parts of the Matrix + * specification and should only be used to advertise support for a feature + * which has not yet landed in the spec. For example, a feature currently + * undergoing the proposal process may appear here and eventually be taken + * off this list once the feature lands in the spec and the server deems it + * reasonable to do so. Servers may wish to keep advertising features here + * after they've been released into the spec to give clients a chance to + * upgrade appropriately. Additionally, clients should avoid using unstable + * features in their stable releases. + */ + get: operations["getVersions"]; + }; + "/_matrix/media/v1/create": { + /** + * Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later + * via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](https://spec.matrix.org/v1.7/client-server-api/#put_matrixmediav3uploadservernamemediaid). + * + * The server may optionally enforce a maximum age for unused IDs, + * and delete media IDs when the client doesn't start the upload in time, + * or when the upload was interrupted and not resumed in time. The server + * should include the maximum POSIX millisecond timestamp to complete the + * upload in the `unused_expires_at` field in the response JSON. The + * recommended default expiration is 24 hours which should be enough time + * to accommodate users on poor connection who find a better connection to + * complete the upload. + * + * As well as limiting the rate of requests to create `mxc://` URIs, the server + * should limit the number of concurrent *pending media uploads* a given + * user can have. A pending media upload is a created `mxc://` URI where (a) + * the media has not yet been uploaded, and (b) has not yet expired (the + * `unused_expires_at` timestamp has not yet passed). In both cases, the + * server should respond with an HTTP 429 error with an errcode of + * `M_LIMIT_EXCEEDED`. + */ + post: operations["createContent"]; + }; + "/_matrix/media/v3/config": { + /** + * This endpoint allows clients to retrieve the configuration of the content + * repository, such as upload limitations. + * Clients SHOULD use this as a guide when using content repository endpoints. + * All values are intentionally left optional. Clients SHOULD follow + * the advice given in the field description when the field is not available. + * + * **NOTE:** Both clients and server administrators should be aware that proxies + * between the client and the server may affect the apparent behaviour of content + * repository APIs, for example, proxies may enforce a lower upload size limit + * than is advertised by the server on this endpoint. + */ + get: operations["getConfig"]; + }; + "/_matrix/media/v3/download/{serverName}/{mediaId}": { + get: operations["getContent"]; + }; + "/_matrix/media/v3/download/{serverName}/{mediaId}/{fileName}": { + /** + * This will download content from the content repository (same as + * the previous endpoint) but replace the target file name with the one + * provided by the caller. + */ + get: operations["getContentOverrideName"]; + }; + "/_matrix/media/v3/preview_url": { + /** + * Get information about a URL for the client. Typically this is called when a + * client sees a URL in a message and wants to render a preview for the user. + * + * **Note:** + * Clients should consider avoiding this endpoint for URLs posted in encrypted + * rooms. Encrypted rooms often contain more sensitive information the users + * do not want to share with the homeserver, and this can mean that the URLs + * being shared should also not be shared with the homeserver. + */ + get: operations["getUrlPreview"]; + }; + "/_matrix/media/v3/thumbnail/{serverName}/{mediaId}": { + /** + * Download a thumbnail of content from the content repository. + * See the [Thumbnails](https://spec.matrix.org/v1.7/client-server-api/#thumbnails) section for more information. + */ + get: operations["getContentThumbnail"]; + }; + "/_matrix/media/v3/upload": { + post: operations["uploadContent"]; + }; + "/_matrix/media/v3/upload/{serverName}/{mediaId}": { + /** + * This endpoint permits uploading content to an `mxc://` URI that was created + * earlier via [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create). + */ + put: operations["uploadContentToMXC"]; + }; +} + +export interface operations { + /** + * Gets discovery information about the domain. The file may include + * additional keys, which MUST follow the Java package naming convention, + * e.g. `com.example.myapp.property`. This ensures property names are + * suitably namespaced for each application and reduces the risk of + * clashes. + * + * Note that this endpoint is not necessarily handled by the homeserver, + * but by another webserver, to be used for discovering the homeserver URL. + */ + getWellknown: { + responses: { + /** Server discovery information. */ + 200: { + schema: { + /** + * Homeserver Information + * @description Used by clients to discover homeserver information. + */ + "m.homeserver": { + /** + * Format: uri + * @description The base URL for the homeserver for client-server connections. + * @example https://matrix.example.com + */ + base_url: string; + }; + /** + * Identity Server Information + * @description Used by clients to discover identity server information. + */ + "m.identity_server"?: { + /** + * Format: uri + * @description The base URL for the identity server for client-server connections. + * @example https://identity.example.com + */ + base_url: string; + }; + } & { [key: string]: { [key: string]: unknown } }; + }; + /** No server discovery information available. */ + 404: unknown; + }; + }; + /** + * This API asks the homeserver to call the + * [`/_matrix/app/v1/ping`](#post_matrixappv1ping) endpoint on the + * application service to ensure that the homeserver can communicate + * with the application service. + * + * This API requires the use of an application service access token (`as_token`) + * instead of a typical client's access token. This API cannot be invoked by + * users who are not identified as application services. Additionally, the + * appservice ID in the path must be the same as the appservice whose `as_token` + * is being used. + */ + pingAppservice: { + parameters: { + path: { + /** + * The appservice ID of the appservice to ping. This must be the same + * as the appservice whose `as_token` is being used to authenticate the + * request. + */ + appserviceId: string; + }; + body: { + body: { + /** + * @description An optional transaction ID that is passed through to the `/_matrix/app/v1/ping` call. + * @example mautrix-go_1683636478256400935_123 + */ + transaction_id?: string; + }; + }; + }; + responses: { + /** The ping was successful. */ + 200: { + schema: { + /** + * @description The duration in milliseconds that the + * [`/_matrix/app/v1/ping`](#post_matrixappv1ping) + * request took from the homeserver's point of view. + */ + duration_ms: number; + }; + }; + /** The application service doesn't have a URL configured. The errcode is `M_URL_NOT_SET`. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** 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`. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The application service returned a bad status, or the connection failed. + * The errcode is `M_BAD_STATUS` or `M_CONNECTION_FAILED`. + * + * For bad statuses, the response may include `status` and `body` + * fields containing the HTTP status code and response body text + * respectively to aid with debugging. + */ + 502: { + schema: { + /** + * @description The HTTP response body returned by the appservice. + * @example {"errcode": "M_UNKNOWN_TOKEN"} + */ + body?: string; + /** + * @description An error code. + * @enum {string} + */ + errcode: "M_BAD_STATUS" | "M_CONNECTION_FAILED"; + /** + * @description A human-readable error message. + * @example Ping returned status 401 + */ + error?: string; + /** + * @description The HTTP status code returned by the appservice. + * @example 401 + */ + status?: number; + }; + }; + /** The connection to the application service timed out. The errcode is `M_CONNECTION_TIMEOUT`. */ + 504: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Optional endpoint - the server is not required to implement this endpoint if it does not + * intend to use or support this functionality. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * An already-authenticated client can call this endpoint to generate a single-use, time-limited, + * token for an unauthenticated client to log in with, becoming logged in as the same user which + * called this endpoint. The unauthenticated client uses the generated token in a `m.login.token` + * login flow with the homeserver. + * + * Clients, both authenticated and unauthenticated, might wish to hide user interface which exposes + * this feature if the server is not offering it. Authenticated clients can check for support on + * a per-user basis with the `m.get_login_token` [capability](https://spec.matrix.org/v1.7/client-server-api/#capabilities-negotiation), + * while unauthenticated clients can detect server support by looking for an `m.login.token` login + * flow with `get_login_token: true` on [`GET /login`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3login). + * + * In v1.7 of the specification, transmission of the generated token to an unauthenticated client is + * left as an implementation detail. Future MSCs such as [MSC3906](https://github.com/matrix-org/matrix-spec-proposals/pull/3906) + * might standarise a way to transmit the token between clients. + * + * The generated token MUST only be valid for a single login, enforced by the server. Clients which + * intend to log in multiple devices must generate a token for each. + * + * With other User-Interactive Authentication (UIA)-supporting endpoints, servers sometimes do not re-prompt + * for verification if the session recently passed UIA. For this endpoint, servers should always re-prompt + * the user for verification to ensure explicit consent is gained for each additional client. + * + * Servers are encouraged to apply stricter than normal rate limiting to this endpoint, such as maximum + * of 1 request per minute. + */ + generateLoginToken: { + parameters: { + body: { + body: { + /** @description Additional authentication information for the user-interactive authentication API. */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + }; + }; + }; + responses: { + /** The login token an unauthenticated client can use to log in as the requesting user. */ + 200: { + schema: { + /** + * @description The time remaining in milliseconds until the homeserver will no longer accept the token. `120000` + * (2 minutes) is recommended as a default. + */ + expires_in_ms: number; + /** @description The login token for the `m.login.token` login flow. */ + login_token: string; + }; + }; + /** + * The request was malformed, or the user does not have an ability to generate tokens for their devices, + * as implied by the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Clients should verify whether the user has an ability to call this endpoint with the `m.get_login_token` + * [capability](https://spec.matrix.org/v1.7/client-server-api/#capabilities-negotiation). + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Queries the server to determine if a given registration token is still + * valid at the time of request. This is a point-in-time check where the + * token might still expire by the time it is used. + * + * Servers should be sure to rate limit this endpoint to avoid brute force + * attacks. + */ + registrationTokenValidity: { + parameters: { + query: { + /** The token to check validity of. */ + token: string; + }; + }; + responses: { + /** The check has a result. */ + 200: { + schema: { + /** + * @description True if the token is still valid, false otherwise. This should + * additionally be false if the token is not a recognised token by + * the server. + */ + valid: boolean; + }; + }; + /** + * The homeserver does not permit registration and thus all tokens are + * considered invalid. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Paginates over the space tree in a depth-first manner to locate child rooms of a given space. + * + * Where a child room is unknown to the local server, federation is used to fill in the details. + * The servers listed in the `via` array should be contacted to attempt to fill in missing rooms. + * + * Only [`m.space.child`](#mspacechild) state events of the room are considered. Invalid child + * rooms and parent events are not covered by this endpoint. + */ + getSpaceHierarchy: { + parameters: { + path: { + /** The room ID of the space to get a hierarchy for. */ + roomId: string; + }; + query: { + /** + * Optional (default `false`) flag to indicate whether or not the server should only consider + * suggested rooms. Suggested rooms are annotated in their [`m.space.child`](#mspacechild) event + * contents. + */ + suggested_only?: boolean; + /** + * Optional limit for the maximum number of rooms to include per response. Must be an integer + * greater than zero. + * + * Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. + */ + limit?: number; + /** + * Optional limit for how far to go into the space. Must be a non-negative integer. + * + * When reached, no further child rooms will be returned. + * + * Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. + */ + max_depth?: number; + /** + * A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot + * be changed from the first request. + */ + from?: string; + }; + }; + responses: { + /** A portion of the space tree, starting at the provided room ID. */ + 200: { + schema: { + /** + * @description A token to supply to `from` to keep paginating the responses. Not present when there are + * no further results. + */ + next_batch?: string; + /** @description The rooms for the current page, with the current filters. */ + rooms: ({ + /** + * Format: uri + * @description The URL for the room's avatar, if one is set. + * @example mxc://example.org/abcdef + */ + avatar_url?: string; + /** + * @description The canonical alias of the room, if any. + * @example #general:example.org + */ + canonical_alias?: string; + /** + * @description Whether guest users may join the room and participate in it. + * If they can, they will be subject to ordinary power level + * rules like any other user. + * @example true + */ + guest_can_join: boolean; + /** + * @description The room's join rule. When not present, the room is assumed to + * be `public`. + * @example public + */ + join_rule?: string; + /** + * @description The name of the room, if any. + * @example General Chat + */ + name?: string; + /** + * @description The number of members joined to the room. + * @example 42 + */ + num_joined_members: number; + /** + * @description The ID of the room. + * @example !abcdefg:example.org + */ + room_id: string; + /** @description The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.7/client-server-api/#mroomcreate)), if any. */ + room_type?: string; + /** + * @description The topic of the room, if any. + * @example All things general + */ + topic?: string; + /** + * @description Whether the room may be viewed by guest users without joining. + * @example false + */ + world_readable: boolean; + } & { + /** + * @description The [`m.space.child`](#mspacechild) events of the space-room, represented + * as [Stripped State Events](#stripped-state) with an added `origin_server_ts` key. + * + * If the room is not a space-room, this should be empty. + */ + children_state: ({ + /** + * EventContent + * @description The `content` for the event. + */ + content: { [key: string]: unknown }; + /** @description The `sender` for the event. */ + sender: string; + /** @description The `state_key` for the event. */ + state_key: string; + /** @description The `type` for the event. */ + type: string; + } & { + /** + * Format: int64 + * @description The `origin_server_ts` for the event. + */ + origin_server_ts: number; + })[]; + /** @description The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.7/client-server-api/#mroomcreate)), if any. */ + room_type?: string; + })[]; + }; + }; + /** + * The request was invalid in some way. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The `from` token is unknown to the server. + * - `suggested_only` or `max_depth` changed during pagination. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The user cannot view or peek on the room. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The room is not set up for peeking. + * - The user has been banned from the room. + * - The room does not exist. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Retrieve all of the child events for a given parent event. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + getRelatingEvents: { + parameters: { + path: { + /** The ID of the room containing the parent event. */ + roomId: string; + /** The ID of the parent event whose child events are to be returned. */ + eventId: string; + }; + query: { + /** + * The pagination token to start returning results from. If not supplied, results + * start at the most recent topological event known to the server. + * + * Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + * `start` token from [`/messages`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomidmessages), + * or a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync). + */ + from?: string; + /** + * The pagination token to stop returning results at. If not supplied, results + * continue up to `limit` or until there are no more events. + * + * Like `from`, this can be a previous token from a prior call to this endpoint + * or from `/messages` or `/sync`. + */ + to?: string; + /** + * The maximum number of results to return in a single `chunk`. The server can + * and should apply a maximum value to this parameter to avoid large responses. + * + * Similarly, the server should apply a default value when not supplied. + */ + limit?: number; + /** + * Optional (default `b`) direction to return events from. If this is set to `f`, events + * will be returned in chronological order starting at `from`. If it + * is set to `b`, events will be returned in *reverse* chronological + * order, again starting at `from`. + */ + dir?: "b" | "f"; + }; + }; + responses: { + /** + * The paginated child events which point to the parent. If no events are + * pointing to the parent or the pagination yields no results, an empty `chunk` + * is returned. + */ + 200: { + schema: { + /** + * ChildEventsChunk + * @description The child events of the requested event, ordered topologically most-recent first. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means there are no more results to fetch and the client should stop paginating. + */ + next_batch?: string; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means this is the start of the result set, i.e. this is the first batch/page. + */ + prev_batch?: string; + }; + }; + /** + * The parent event was not found or the user does not have permission to read + * this event (it might be contained in history that is not accessible to the user). + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Retrieve all of the child events for a given parent event which relate to the parent + * using the given `relType`. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + getRelatingEventsWithRelType: { + parameters: { + path: { + /** The ID of the room containing the parent event. */ + roomId: string; + /** The ID of the parent event whose child events are to be returned. */ + eventId: string; + /** The [relationship type](https://spec.matrix.org/v1.7/client-server-api/#relationship-types) to search for. */ + relType: string; + }; + query: { + /** + * The pagination token to start returning results from. If not supplied, results + * start at the most recent topological event known to the server. + * + * Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + * `start` token from [`/messages`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomidmessages), + * or a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync). + */ + from?: string; + /** + * The pagination token to stop returning results at. If not supplied, results + * continue up to `limit` or until there are no more events. + * + * Like `from`, this can be a previous token from a prior call to this endpoint + * or from `/messages` or `/sync`. + */ + to?: string; + /** + * The maximum number of results to return in a single `chunk`. The server can + * and should apply a maximum value to this parameter to avoid large responses. + * + * Similarly, the server should apply a default value when not supplied. + */ + limit?: number; + /** + * Optional (default `b`) direction to return events from. If this is set to `f`, events + * will be returned in chronological order starting at `from`. If it + * is set to `b`, events will be returned in *reverse* chronological + * order, again starting at `from`. + */ + dir?: "b" | "f"; + }; + }; + responses: { + /** + * The paginated child events which point to the parent. If no events are + * pointing to the parent or the pagination yields no results, an empty `chunk` + * is returned. + */ + 200: { + schema: { + /** + * ChildEventsChunk + * @description The child events of the requested event, ordered topologically + * most-recent first. The events returned will match the `relType` + * supplied in the URL. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means there are no more results to fetch and the client should stop paginating. + */ + next_batch?: string; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means this is the start of the result set, i.e. this is the first batch/page. + */ + prev_batch?: string; + }; + }; + /** + * The parent event was not found or the user does not have permission to read + * this event (it might be contained in history that is not accessible to the user). + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Retrieve all of the child events for a given parent event which relate to the parent + * using the given `relType` and have the given `eventType`. + * + * Note that when paginating the `from` token should be "after" the `to` token in + * terms of topological ordering, because it is only possible to paginate "backwards" + * through events, starting at `from`. + * + * For example, passing a `from` token from page 2 of the results, and a `to` token + * from page 1, would return the empty set. The caller can use a `from` token from + * page 1 and a `to` token from page 2 to paginate over the same range, however. + */ + getRelatingEventsWithRelTypeAndEventType: { + parameters: { + path: { + /** The ID of the room containing the parent event. */ + roomId: string; + /** The ID of the parent event whose child events are to be returned. */ + eventId: string; + /** The [relationship type](https://spec.matrix.org/v1.7/client-server-api/#relationship-types) to search for. */ + relType: string; + /** + * The event type of child events to search for. + * + * Note that in encrypted rooms this will typically always be `m.room.encrypted` + * regardless of the event type contained within the encrypted payload. + */ + eventType: string; + }; + query: { + /** + * The pagination token to start returning results from. If not supplied, results + * start at the most recent topological event known to the server. + * + * Can be a `next_batch` or `prev_batch` token from a previous call, or a returned + * `start` token from [`/messages`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomidmessages), + * or a `next_batch` token from [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync). + */ + from?: string; + /** + * The pagination token to stop returning results at. If not supplied, results + * continue up to `limit` or until there are no more events. + * + * Like `from`, this can be a previous token from a prior call to this endpoint + * or from `/messages` or `/sync`. + */ + to?: string; + /** + * The maximum number of results to return in a single `chunk`. The server can + * and should apply a maximum value to this parameter to avoid large responses. + * + * Similarly, the server should apply a default value when not supplied. + */ + limit?: number; + /** + * Optional (default `b`) direction to return events from. If this is set to `f`, events + * will be returned in chronological order starting at `from`. If it + * is set to `b`, events will be returned in *reverse* chronological + * order, again starting at `from`. + */ + dir?: "b" | "f"; + }; + }; + responses: { + /** + * The paginated child events which point to the parent. If no events are + * pointing to the parent or the pagination yields no results, an empty `chunk` + * is returned. + */ + 200: { + schema: { + /** + * ChildEventsChunk + * @description The child events of the requested event, ordered topologically most-recent + * first. The events returned will match the `relType` and `eventType` supplied + * in the URL. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means there are no more results to fetch and the client should stop paginating. + */ + next_batch?: string; + /** + * @description An opaque string representing a pagination token. The absence of this token + * means this is the start of the result set, i.e. this is the first batch/page. + */ + prev_batch?: string; + }; + }; + /** + * The parent event was not found or the user does not have permission to read + * this event (it might be contained in history that is not accessible to the user). + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API is used to paginate through the list of the thread roots in a given room. + * + * Optionally, the returned list may be filtered according to whether the requesting + * user has participated in the thread. + */ + getThreadRoots: { + parameters: { + path: { + /** The room ID where the thread roots are located. */ + roomId: string; + }; + query: { + /** + * Optional (default `all`) flag to denote which thread roots are of interest to the caller. + * When `all`, all thread roots found in the room are returned. When `participated`, only + * thread roots for threads the user has [participated in](https://spec.matrix.org/v1.7/client-server-api/#server-side-aggregation-of-mthread-relationships) + * will be returned. + */ + include?: "all" | "participated"; + /** + * Optional limit for the maximum number of thread roots to include per response. Must be an integer + * greater than zero. + * + * Servers should apply a default value, and impose a maximum value to avoid resource exhaustion. + */ + limit?: number; + /** + * A pagination token from a previous result. When not provided, the server starts paginating from + * the most recent event visible to the user (as per history visibility rules; topologically). + */ + from?: string; + }; + }; + responses: { + /** A portion of the available thread roots in the room, based on the filter criteria. */ + 200: { + schema: { + /** + * @description The thread roots, ordered by the `latest_event` in each event's aggregated children. All events + * returned include bundled [aggregations](https://spec.matrix.org/v1.7/client-server-api/#aggregations-of-child-events). + * + * If the thread root event was sent by an [ignored user](https://spec.matrix.org/v1.7/client-server-api/#ignoring-users), the + * event is returned redacted to the caller. This is to simulate the same behaviour of a client doing + * aggregation locally on the thread. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token to supply to `from` to keep paginating the responses. Not present when there are + * no further results. + */ + next_batch?: string; + }; + }; + /** + * The request was invalid in some way. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The `from` token is unknown to the server. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The user cannot view or peek on the room. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The room is not set up for peeking. + * - The user has been banned from the room. + * - The room does not exist. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get the ID of the event closest to the given timestamp, in the + * direction specified by the `dir` parameter. + * + * If the server does not have all of the room history and does not have + * an event suitably close to the requested timestamp, it can use the + * corresponding [federation endpoint](https://spec.matrix.org/v1.7/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid) + * to ask other servers for a suitable event. + * + * After calling this endpoint, clients can call + * [`/rooms/{roomId}/context/{eventId}`](#get_matrixclientv3roomsroomidcontexteventid) + * to obtain a pagination token to retrieve the events around the returned event. + * + * The event returned by this endpoint could be an event that the client + * cannot render, and so may need to paginate in order to locate an event + * that it can display, which may end up being outside of the client's + * suitable range. Clients can employ different strategies to display + * something reasonable to the user. For example, the client could try + * paginating in one direction for a while, while looking at the + * timestamps of the events that it is paginating through, and if it + * exceeds a certain difference from the target timestamp, it can try + * paginating in the opposite direction. The client could also simply + * paginate in one direction and inform the user that the closest event + * found in that direction is outside of the expected range. + */ + getEventByTimestamp: { + parameters: { + path: { + /** The ID of the room to search */ + roomId: string; + }; + query: { + /** + * The timestamp to search from, as given in milliseconds + * since the Unix epoch. + */ + ts: number; + /** The direction in which to search. `f` for forwards, `b` for backwards. */ + dir: "f" | "b"; + }; + }; + responses: { + /** An event was found matching the search parameters. */ + 200: { + schema: { + /** @description The ID of the event found */ + event_id: string; + /** + * @description The event's timestamp, in milliseconds since the Unix epoch. + * This makes it easy to do a quick comparison to see if the + * `event_id` fetched is too far out of range to be useful for your + * use case. + */ + origin_server_ts: number; + }; + }; + /** No event was found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Gets a list of the third-party identifiers that the homeserver has + * associated with the user's account. + * + * This is *not* the same as the list of third-party identifiers bound to + * the user's Matrix ID in identity servers. + * + * Identifiers in this list may be used by the homeserver as, for example, + * identifiers that it will accept to reset the user's account password. + */ + getAccount3PIDs: { + responses: { + /** The lookup was successful. */ + 200: { + schema: { + threepids?: { + /** + * Format: int64 + * @description The timestamp, in milliseconds, when the homeserver associated the third-party identifier with the user. + */ + added_at: number; + /** @description The third-party identifier address. */ + address: string; + /** + * @description The medium of the third-party identifier. + * @enum {string} + */ + medium: "email" | "msisdn"; + /** + * Format: int64 + * @description The timestamp, in milliseconds, when the identifier was + * validated by the identity server. + */ + validated_at: number; + }[]; + }; + }; + }; + }; + /** + * Adds contact information to the user's account. + * + * This endpoint is deprecated in favour of the more specific `/3pid/add` + * and `/3pid/bind` endpoints. + * + * **Note:** + * Previously this endpoint supported a `bind` parameter. This parameter + * has been removed, making this endpoint behave as though it was `false`. + * This results in this endpoint being an equivalent to `/3pid/bind` rather + * than dual-purpose. + */ + post3PIDs: { + parameters: { + body: { + body: { + /** + * ThreePidCredentials + * @description The third-party credentials to associate with the account. + */ + three_pid_creds: { + /** @description The client secret used in the session with the identity server. */ + client_secret: string; + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + */ + id_access_token: string; + /** @description The identity server to use. */ + id_server: string; + /** @description The session identifier given by the identity server. */ + sid: string; + }; + }; + }; + }; + responses: { + /** The addition was successful. */ + 200: { + schema: { + /** + * Format: uri + * @description An optional field containing a URL where the client must + * submit the validation token to, with identical parameters + * to the Identity Service API's `POST + * /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the + * user (if applicable), who should then be prompted to provide it + * to the client. + * + * If this field is not present, the client can assume that + * verification will happen without the client's involvement + * provided the homeserver advertises this specification version + * in the `/versions` response (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** The credentials could not be verified with the identity server. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Adds contact information to the user's account. Homeservers should use 3PIDs added + * through this endpoint for password resets instead of relying on the identity server. + * + * Homeservers should prevent the caller from adding a 3PID to their account if it has + * already been added to another user's account on the homeserver. + */ + add3PID: { + parameters: { + body: { + body: { + /** + * @description Additional authentication information for the + * user-interactive authentication API. + */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** + * @description The client secret used in the session with the homeserver. + * @example d0nt-T3ll + */ + client_secret: string; + /** + * @description The session identifier given by the homeserver. + * @example abc123987 + */ + sid: string; + }; + }; + }; + responses: { + /** The addition was successful. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Binds a 3PID to the user's account through the specified identity server. + * + * Homeservers should not prevent this request from succeeding if another user + * has bound the 3PID. Homeservers should simply proxy any errors received by + * the identity server to the caller. + * + * Homeservers should track successful binds so they can be unbound later. + */ + bind3PID: { + parameters: { + body: { + body: { + /** @description The client secret used in the session with the identity server. */ + client_secret: string; + /** @description An access token previously registered with the identity server. */ + id_access_token: string; + /** @description The identity server to use. */ + id_server: string; + /** @description The session identifier given by the identity server. */ + sid: string; + }; + }; + }; + responses: { + /** The addition was successful. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Removes a third-party identifier from the user's account. This might not + * cause an unbind of the identifier from the identity server. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + delete3pidFromAccount: { + parameters: { + body: { + body: { + /** + * @description The third-party address being removed. + * @example example@example.org + */ + address: string; + /** + * @description The identity server to unbind from. If not provided, the homeserver + * MUST use the `id_server` the identifier was added through. If the + * homeserver does not know the original `id_server`, it MUST return + * a `id_server_unbind_result` of `no-support`. + * @example example.org + */ + id_server?: string; + /** + * @description The medium of the third-party identifier being removed. + * @example email + * @enum {string} + */ + medium: "email" | "msisdn"; + }; + }; + }; + responses: { + /** + * The homeserver has disassociated the third-party identifier from the + * user. + */ + 200: { + schema: { + /** + * @description An indicator as to whether or not the homeserver was able to unbind + * the 3PID from the identity server. `success` indicates that the + * identity server has unbound the identifier whereas `no-support` + * indicates that the identity server refuses to support the request + * or the homeserver was not able to determine an identity server to + * unbind from. + * @example success + * @enum {string} + */ + id_server_unbind_result: "no-support" | "success"; + }; + }; + }; + }; + /** + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding an email address to an + * account. This API's parameters and response are identical to that of + * the [`/register/email/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint. The homeserver should validate + * the email itself, either by sending a validation email itself or by using + * a service it has control over. + */ + requestTokenTo3PIDEmail: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The email address to validate. + * @example alice@example.org + */ + email: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The server will only send an email if the `send_attempt` + * is a number greater than the most recent one which it has seen, + * scoped to that `email` + `client_secret` pair. This is to + * avoid repeatedly sending the same email in the case of request + * retries between the POSTing user and the identity server. + * The client should increment this value if they desire a new + * email (e.g. a reminder) to be sent. If they do not, the server + * should respond with success but not resend the email. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** + * An email was sent to the given address. Note that this may be an + * email containing the validation token or it may be informing the + * user of an error. + */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * The third-party identifier is already in use on the homeserver, or + * the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + * can be returned if the server does not trust/support the identity server + * provided in the request. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The homeserver does not allow the third-party identifier as a + * contact option. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. This API should + * be used to request validation tokens when adding a phone number to an + * account. This API's parameters and response are identical to that of + * the [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint. The homeserver should validate + * the phone number itself, either by sending a validation message itself or by using + * a service it has control over. + */ + requestTokenTo3PIDMSISDN: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The two-letter uppercase ISO-3166-1 alpha-2 country code that the + * number in `phone_number` should be parsed as if it were dialled from. + * @example GB + */ + country: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The phone number to validate. + * @example 07700900001 + */ + phone_number: string; + /** + * @description The server will only send an SMS if the `send_attempt` is a + * number greater than the most recent one which it has seen, + * scoped to that `country` + `phone_number` + `client_secret` + * triple. This is to avoid repeatedly sending the same SMS in + * the case of request retries between the POSTing user and the + * identity server. The client should increment this value if + * they desire a new SMS (e.g. a reminder) to be sent. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** An SMS message was sent to the given phone number. */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * The third-party identifier is already in use on the homeserver, or + * the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + * can be returned if the server does not trust/support the identity server + * provided in the request. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The homeserver does not allow the third-party identifier as a + * contact option. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Removes a user's third-party identifier from the provided identity server + * without removing it from the homeserver. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + unbind3pidFromAccount: { + parameters: { + body: { + body: { + /** + * @description The third-party address being removed. + * @example example@example.org + */ + address: string; + /** + * @description The identity server to unbind from. If not provided, the homeserver + * MUST use the `id_server` the identifier was added through. If the + * homeserver does not know the original `id_server`, it MUST return + * a `id_server_unbind_result` of `no-support`. + * @example example.org + */ + id_server?: string; + /** + * @description The medium of the third-party identifier being removed. + * @example email + * @enum {string} + */ + medium: "email" | "msisdn"; + }; + }; + }; + responses: { + /** + * The identity server has disassociated the third-party identifier from the + * user. + */ + 200: { + schema: { + /** + * @description An indicator as to whether or not the identity server was able to unbind + * the 3PID. `success` indicates that the identity server has unbound the + * identifier whereas `no-support` indicates that the identity server + * refuses to support the request or the homeserver was not able to determine + * an identity server to unbind from. + * @example success + * @enum {string} + */ + id_server_unbind_result: "no-support" | "success"; + }; + }; + }; + }; + /** + * Deactivate the user's account, removing all ability for the user to + * login again. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. + * + * Unlike other endpoints, this endpoint does not take an `id_access_token` + * parameter because the homeserver is expected to sign the request to the + * identity server instead. + */ + deactivateAccount: { + parameters: { + body: { + body: { + /** @description Additional authentication information for the user-interactive authentication API. */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** + * @description The identity server to unbind all of the user's 3PIDs from. + * If not provided, the homeserver MUST use the `id_server` + * that was originally use to bind each identifier. If the + * homeserver does not know which `id_server` that was, + * it must return an `id_server_unbind_result` of + * `no-support`. + * @example example.org + */ + id_server?: string; + }; + }; + }; + responses: { + /** The account has been deactivated. */ + 200: { + schema: { + /** + * @description An indicator as to whether or not the homeserver was able to unbind + * the user's 3PIDs from the identity server(s). `success` indicates + * that all identifiers have been unbound from the identity server while + * `no-support` indicates that one or more identifiers failed to unbind + * due to the identity server refusing the request or the homeserver + * being unable to determine an identity server to unbind from. This + * must be `success` if the homeserver has no identifiers to unbind + * for the user. + * @example success + * @enum {string} + */ + id_server_unbind_result: "success" | "no-support"; + }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Changes the password for an account on this homeserver. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api) to + * ensure the user changing the password is actually the owner of the + * account. + * + * An access token should be submitted to this endpoint if the client has + * an active session. + * + * The homeserver may change the flows available depending on whether a + * valid access token is provided. The homeserver SHOULD NOT revoke the + * access token provided in the request. Whether other access tokens for + * the user are revoked depends on the request parameters. + */ + changePassword: { + parameters: { + body: { + body: { + /** @description Additional authentication information for the user-interactive authentication API. */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** + * @description Whether the user's other access tokens, and their associated devices, should be + * revoked if the request succeeds. Defaults to true. + * + * When `false`, the server can still take advantage of the [soft logout method](https://spec.matrix.org/v1.7/client-server-api/#soft-logout) + * for the user's remaining devices. + * @example true + */ + logout_devices?: boolean; + /** + * @description The new password for the account. + * @example ihatebananas + */ + new_password: string; + }; + }; + }; + responses: { + /** The password has been changed. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * The homeserver must check that the given email address **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/email/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registeremailrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given email address could be found. The server may instead send an + * email to the given address prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the email itself, either by sending a + * validation email itself or by using a service it has control over. + */ + requestTokenToResetPasswordEmail: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The email address to validate. + * @example alice@example.org + */ + email: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The server will only send an email if the `send_attempt` + * is a number greater than the most recent one which it has seen, + * scoped to that `email` + `client_secret` pair. This is to + * avoid repeatedly sending the same email in the case of request + * retries between the POSTing user and the identity server. + * The client should increment this value if they desire a new + * email (e.g. a reminder) to be sent. If they do not, the server + * should respond with success but not resend the email. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** An email was sent to the given address. */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * The referenced third-party identifier is not recognised by the + * homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + * can be returned if the server does not trust/support the identity server + * provided in the request. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The homeserver does not allow the third-party identifier as a + * contact option. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * The homeserver must check that the given phone number **is + * associated** with an account on this homeserver. This API should be + * used to request validation tokens when authenticating for the + * `/account/password` endpoint. + * + * This API's parameters and response are identical to that of the + * [`/register/msisdn/requestToken`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3registermsisdnrequesttoken) + * endpoint, except that + * `M_THREEPID_NOT_FOUND` may be returned if no account matching the + * given phone number could be found. The server may instead send the SMS + * to the given phone number prompting the user to create an account. + * `M_THREEPID_IN_USE` may not be returned. + * + * The homeserver should validate the phone number itself, either by sending a + * validation message itself or by using a service it has control over. + */ + requestTokenToResetPasswordMSISDN: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The two-letter uppercase ISO-3166-1 alpha-2 country code that the + * number in `phone_number` should be parsed as if it were dialled from. + * @example GB + */ + country: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The phone number to validate. + * @example 07700900001 + */ + phone_number: string; + /** + * @description The server will only send an SMS if the `send_attempt` is a + * number greater than the most recent one which it has seen, + * scoped to that `country` + `phone_number` + `client_secret` + * triple. This is to avoid repeatedly sending the same SMS in + * the case of request retries between the POSTing user and the + * identity server. The client should increment this value if + * they desire a new SMS (e.g. a reminder) to be sent. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** An SMS message was sent to the given phone number. */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * The referenced third-party identifier is not recognised by the + * homeserver, or the request was invalid. The error code `M_SERVER_NOT_TRUSTED` + * can be returned if the server does not trust/support the identity server + * provided in the request. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The homeserver does not allow the third-party identifier as a + * contact option. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Gets information about the owner of a given access token. + * + * Note that, as with the rest of the Client-Server API, + * Application Services may masquerade as users within their + * namespace by giving a `user_id` query parameter. In this + * situation, the server should verify that the given `user_id` + * is registered by the appservice, and return it in the response + * body. + */ + getTokenOwner: { + parameters: {}; + responses: { + /** The token belongs to a known user. */ + 200: { + schema: { + /** + * @description Device ID associated with the access token. If no device + * is associated with the access token (such as in the case + * of application services) then this field can be omitted. + * Otherwise this is required. + */ + device_id?: string; + /** + * @description When `true`, the user is a [Guest User](#guest-access). When + * not present or `false`, the user is presumed to be a non-guest + * user. + */ + is_guest?: boolean; + /** @description The user ID that owns the access token. */ + user_id: string; + }; + }; + /** The token is not recognised */ + 401: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The appservice cannot masquerade as the user or has not registered them. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Gets information about a particular user. + * + * This API may be restricted to only be called by the user being looked + * up, or by a server admin. Server-local administrator privileges are not + * specified in this document. + */ + getWhoIs: { + parameters: { + path: { + /** The user to look up. */ + userId: string; + }; + }; + responses: { + /** The lookup was successful. */ + 200: { + schema: { + /** @description Each key is an identifier for one of the user's devices. */ + devices?: { + [key: string]: { + /** @description A user's sessions (i.e. what they did with an access token from one login). */ + sessions?: { + /** @description Information particular connections in the session. */ + connections?: { + /** @description Most recently seen IP address of the session. */ + ip?: string; + /** + * Format: int64 + * @description Unix timestamp that the session was last active. + */ + last_seen?: number; + /** @description User agent string last seen in the session. */ + user_agent?: string; + }[]; + }[]; + }; + }; + /** @description The Matrix user ID of the user. */ + user_id?: string; + }; + }; + }; + }; + /** + * Gets information about the server's supported feature set + * and other relevant capabilities. + */ + getCapabilities: { + parameters: {}; + responses: { + /** The capabilities of the server. */ + 200: { + schema: { + /** + * Capabilities + * @description The custom capabilities the server supports, using the + * Java package naming convention. + */ + capabilities: { + /** + * ChangePasswordCapability + * @description Capability to indicate if the user can change their password. + */ + "m.change_password"?: { + /** + * @description True if the user can change their password, false otherwise. + * @example false + */ + enabled: boolean; + }; + /** + * RoomVersionsCapability + * @description The room versions the server supports. + */ + "m.room_versions"?: { + /** @description A detailed description of the room versions the server supports. */ + available: { [key: string]: "stable" | "unstable" }; + /** + * @description The default room version the server is using for new rooms. + * @example 1 + */ + default: string; + }; + } & { [key: string]: { [key: string]: unknown } }; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Create a new room with various configuration options. + * + * The server MUST apply the normal state resolution rules when creating + * the new room, including checking power levels for each event. It MUST + * apply the events implied by the request in the following order: + * + * 1. The `m.room.create` event itself. Must be the first event in the + * room. + * + * 2. An `m.room.member` event for the creator to join the room. This is + * needed so the remaining events can be sent. + * + * 3. A default `m.room.power_levels` event, giving the room creator + * (and not other members) permission to send state events. Overridden + * by the `power_level_content_override` parameter. + * + * 4. An `m.room.canonical_alias` event if `room_alias_name` is given. + * + * 5. Events set by the `preset`. Currently these are the `m.room.join_rules`, + * `m.room.history_visibility`, and `m.room.guest_access` state events. + * + * 6. Events listed in `initial_state`, in the order that they are + * listed. + * + * 7. Events implied by `name` and `topic` (`m.room.name` and `m.room.topic` + * state events). + * + * 8. Invite events implied by `invite` and `invite_3pid` (`m.room.member` with + * `membership: invite` and `m.room.third_party_invite`). + * + * The available presets do the following with respect to room state: + * + * | Preset | `join_rules` | `history_visibility` | `guest_access` | Other | + * |------------------------|--------------|----------------------|----------------|-------| + * | `private_chat` | `invite` | `shared` | `can_join` | | + * | `trusted_private_chat` | `invite` | `shared` | `can_join` | All invitees are given the same power level as the room creator. | + * | `public_chat` | `public` | `shared` | `forbidden` | | + * + * The server will create a `m.room.create` event in the room with the + * requesting user as the creator, alongside other keys provided in the + * `creation_content`. + */ + createRoom: { + parameters: { + body: { + /** The desired room configuration. */ + body: { + /** + * CreationContent + * @description Extra keys, such as `m.federate`, to be added to the content + * of the [`m.room.create`](https://spec.matrix.org/v1.7/client-server-api/#mroomcreate) event. The server will overwrite the following + * keys: `creator`, `room_version`. Future versions of the specification + * may allow the server to overwrite other keys. + */ + creation_content?: { [key: string]: unknown }; + /** + * @description A list of state events to set in the new room. This allows + * the user to override the default state events set in the new + * room. The expected format of the state events are an object + * with type, state_key and content keys set. + * + * Takes precedence over events set by `preset`, but gets + * overridden by `name` and `topic` keys. + */ + initial_state?: { + /** @description The content of the event. */ + content: { [key: string]: unknown }; + /** @description The state_key of the state event. Defaults to an empty string. */ + state_key?: string; + /** @description The type of event to send. */ + type: string; + }[]; + /** + * @description A list of user IDs to invite to the room. This will tell the + * server to invite everyone in the list to the newly created room. + */ + invite?: string[]; + /** + * @description A list of objects representing third-party IDs to invite into + * the room. + */ + invite_3pid?: { + /** @description The invitee's third-party identifier. */ + address: string; + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + */ + id_access_token: string; + /** @description The hostname+port of the identity server which should be used for third-party identifier lookups. */ + id_server: string; + /** + * @description The kind of address being passed in the address field, for example `email` + * (see [the list of recognised values](https://spec.matrix.org/v1.7/appendices/#3pid-types)). + */ + medium: string; + }[]; + /** + * @description This flag makes the server set the `is_direct` flag on the + * `m.room.member` events sent to the users in `invite` and + * `invite_3pid`. See [Direct Messaging](https://spec.matrix.org/v1.7/client-server-api/#direct-messaging) for more information. + */ + is_direct?: boolean; + /** + * @description If this is included, an `m.room.name` event will be sent + * into the room to indicate the name of the room. See Room + * Events for more information on `m.room.name`. + */ + name?: string; + /** + * Power Level Event Content + * @description The power level content to override in the default power level + * event. This object is applied on top of the generated + * [`m.room.power_levels`](https://spec.matrix.org/v1.7/client-server-api/#mroompower_levels) + * event content prior to it being sent to the room. Defaults to + * overriding nothing. + */ + power_level_content_override?: { [key: string]: unknown }; + /** + * @description Convenience parameter for setting various default state events + * based on a preset. + * + * If unspecified, the server should use the `visibility` to determine + * which preset to use. A visbility of `public` equates to a preset of + * `public_chat` and `private` visibility equates to a preset of + * `private_chat`. + * @enum {string} + */ + preset?: "private_chat" | "public_chat" | "trusted_private_chat"; + /** + * @description The desired room alias **local part**. If this is included, a + * room alias will be created and mapped to the newly created + * room. The alias will belong on the *same* homeserver which + * created the room. For example, if this was set to "foo" and + * sent to the homeserver "example.com" the complete room alias + * would be `#foo:example.com`. + * + * The complete room alias will become the canonical alias for + * the room and an `m.room.canonical_alias` event will be sent + * into the room. + */ + room_alias_name?: string; + /** + * @description The room version to set for the room. If not provided, the homeserver is + * to use its configured default. If provided, the homeserver will return a + * 400 error with the errcode `M_UNSUPPORTED_ROOM_VERSION` if it does not + * support the room version. + * @example 1 + */ + room_version?: string; + /** + * @description If this is included, an `m.room.topic` event will be sent + * into the room to indicate the topic for the room. See Room + * Events for more information on `m.room.topic`. + */ + topic?: string; + /** + * @description A `public` visibility indicates that the room will be shown + * in the published room list. A `private` visibility will hide + * the room from the published room list. Rooms default to + * `private` visibility if this key is not included. NB: This + * should not be confused with `join_rules` which also uses the + * word `public`. + * @enum {string} + */ + visibility?: "public" | "private"; + }; + }; + }; + responses: { + /** Information about the newly created room. */ + 200: { + schema: { + /** @description The created room's ID. */ + room_id: string; + }; + }; + /** + * The request is invalid. A meaningful `errcode` and description + * error text will be returned. Example reasons for rejection include: + * + * - The request body is malformed (`errcode` set to `M_BAD_JSON` + * or `M_NOT_JSON`). + * + * - The room alias specified is already taken (`errcode` set to + * `M_ROOM_IN_USE`). + * + * - The initial state implied by the parameters to the request is + * invalid: for example, the user's `power_level` is set below + * that necessary to set the room name (`errcode` set to + * `M_INVALID_ROOM_STATE`). + * + * - The homeserver doesn't support the requested room version, or + * one or more users being invited to the new room are residents + * of a homeserver which does not support the requested room version. + * The `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these + * cases. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Deletes the given devices, and invalidates any access token associated with them. + */ + deleteDevices: { + parameters: { + body: { + body: { + /** + * @description Additional authentication information for the + * user-interactive authentication API. + */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** + * @description The list of device IDs to delete. + * @example [ + * "QBUAZIFURK", + * "AUIECTSRND" + * ] + */ + devices: string[]; + }; + }; + }; + responses: { + /** + * The devices were successfully removed, or had been removed + * previously. + */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + }; + }; + /** Gets information about all devices for the current user. */ + getDevices: { + responses: { + /** Device information */ + 200: { + schema: { + /** @description A list of all registered devices for this user. */ + devices?: { + /** + * @description Identifier of this device. + * @example QBUAZIFURK + */ + device_id: string; + /** + * @description Display name set by the user for this device. Absent if no name has been + * set. + * @example android + */ + display_name?: string; + /** + * @description The IP address where this device was last seen. (May be a few minutes out + * of date, for efficiency reasons). + * @example 1.2.3.4 + */ + last_seen_ip?: string; + /** + * Format: int64 + * @description The timestamp (in milliseconds since the unix epoch) when this devices + * was last seen. (May be a few minutes out of date, for efficiency + * reasons). + * @example 1474491775024 + */ + last_seen_ts?: number; + }[]; + }; + }; + }; + }; + /** Gets information on a single device, by device id. */ + getDevice: { + parameters: { + path: { + /** The device to retrieve. */ + deviceId: string; + }; + }; + responses: { + /** Device information */ + 200: { + schema: { + /** + * @description Identifier of this device. + * @example QBUAZIFURK + */ + device_id: string; + /** + * @description Display name set by the user for this device. Absent if no name has been + * set. + * @example android + */ + display_name?: string; + /** + * @description The IP address where this device was last seen. (May be a few minutes out + * of date, for efficiency reasons). + * @example 1.2.3.4 + */ + last_seen_ip?: string; + /** + * Format: int64 + * @description The timestamp (in milliseconds since the unix epoch) when this devices + * was last seen. (May be a few minutes out of date, for efficiency + * reasons). + * @example 1474491775024 + */ + last_seen_ts?: number; + }; + }; + /** The current user has no device with the given ID. */ + 404: unknown; + }; + }; + /** Updates the metadata on the given device. */ + updateDevice: { + parameters: { + path: { + /** The device to update. */ + deviceId: string; + }; + body: { + /** New information for the device. */ + body: { + /** + * @description The new display name for this device. If not given, the + * display name is unchanged. + */ + display_name?: string; + }; + }; + }; + responses: { + /** The device was successfully updated. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The current user has no device with the given ID. */ + 404: unknown; + }; + }; + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + * + * Deletes the given device, and invalidates any access token associated with it. + */ + deleteDevice: { + parameters: { + path: { + /** The device to delete. */ + deviceId: string; + }; + body: { + body: { + /** + * @description Additional authentication information for the + * user-interactive authentication API. + */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + }; + }; + }; + responses: { + /** + * The device was successfully removed, or had been removed + * previously. + */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + }; + }; + /** + * Updates the visibility of a given room on the application service's room + * directory. + * + * This API is similar to the room directory visibility API used by clients + * to update the homeserver's more general room directory. + * + * This API requires the use of an application service access token (`as_token`) + * instead of a typical client's access_token. This API cannot be invoked by + * users who are not identified as application services. + */ + updateAppserviceRoomDirectoryVisibility: { + parameters: { + path: { + /** + * The protocol (network) ID to update the room list for. This would + * have been provided by the application service as being listed as + * a supported protocol. + */ + networkId: string; + /** The room ID to add to the directory. */ + roomId: string; + }; + body: { + body: { + /** + * @description Whether the room should be visible (public) in the directory + * or not (private). + * @example public + * @enum {string} + */ + visibility: "public" | "private"; + }; + }; + }; + responses: { + /** The room's directory visibility has been updated. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** Gets the visibility of a given room on the server's public room directory. */ + getRoomVisibilityOnDirectory: { + parameters: { + path: { + /** The room ID. */ + roomId: string; + }; + }; + responses: { + /** The visibility of the room in the directory */ + 200: { + schema: { + /** + * @description The visibility of the room in the directory. + * @enum {string} + */ + visibility?: "private" | "public"; + }; + }; + /** The room is not known to the server */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Sets the visibility of a given room in the server's public room + * directory. + * + * Servers may choose to implement additional access control checks + * here, for instance that room visibility can only be changed by + * the room creator or a server administrator. + */ + setRoomVisibilityOnDirectory: { + parameters: { + path: { + /** The room ID. */ + roomId: string; + }; + body: { + /** The new visibility for the room on the room directory. */ + body: { + /** + * @description The new visibility setting for the room. + * Defaults to 'public'. + * @enum {string} + */ + visibility?: "private" | "public"; + }; + }; + }; + responses: { + /** The visibility was updated, or no change was needed. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The room is not known to the server */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Requests that the server resolve a room alias to a room ID. + * + * The server will use the federation API to resolve the alias if the + * domain part of the alias does not correspond to the server's own + * domain. + */ + getRoomIdByAlias: { + parameters: { + path: { + /** + * The room alias. Its format is defined + * [in the appendices](https://spec.matrix.org/v1.7/appendices/#room-aliases). + */ + roomAlias: string; + }; + }; + responses: { + /** The room ID and other information for this alias. */ + 200: { + schema: { + /** @description The room ID for this room alias. */ + room_id?: string; + /** @description A list of servers that are aware of this room alias. */ + servers?: string[]; + }; + }; + /** The given `roomAlias` is not a valid room alias. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** There is no mapped room ID for this room alias. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + setRoomAlias: { + parameters: { + path: { + /** + * The room alias to set. Its format is defined + * [in the appendices](https://spec.matrix.org/v1.7/appendices/#room-aliases). + */ + roomAlias: string; + }; + body: { + /** Information about this room alias. */ + body: { + /** @description The room ID to set. */ + room_id: string; + }; + }; + }; + responses: { + /** The mapping was created. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The given `roomAlias` is not a valid room alias. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** A room alias with that name already exists. */ + 409: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Remove a mapping of room alias to room ID. + * + * Servers may choose to implement additional access control checks here, for instance that + * room aliases can only be deleted by their creator or a server administrator. + * + * **Note:** + * Servers may choose to update the `alt_aliases` for the `m.room.canonical_alias` + * state event in the room when an alias is removed. Servers which choose to update the + * canonical alias event are recommended to, in addition to their other relevant permission + * checks, delete the alias and return a successful response even if the user does not + * have permission to update the `m.room.canonical_alias` event. + */ + deleteRoomAlias: { + parameters: { + path: { + /** + * The room alias to remove. Its format is defined + * [in the appendices](https://spec.matrix.org/v1.7/appendices/#room-aliases). + */ + roomAlias: string; + }; + }; + responses: { + /** The mapping was deleted. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** There is no mapped room ID for this room alias. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This will listen for new events and return them to the caller. This will + * block until an event is received, or until the `timeout` is reached. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) + * endpoint with a `since` parameter. See + * the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + getEvents: { + parameters: { + query: { + /** + * The token to stream from. This token is either from a previous + * request to this API or from the initial sync API. + */ + from?: string; + /** The maximum time in milliseconds to wait for an event. */ + timeout?: number; + }; + }; + responses: { + /** The events received, which may be none. */ + 200: { + schema: { + /** @description An array of events. */ + chunk?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token which correlates to the end of `chunk`. This + * token should be used in the next request to `/events`. + */ + end?: string; + /** + * @description A token which correlates to the start of `chunk`. This + * is usually the same token supplied to `from=`. + */ + start?: string; + }; + }; + /** Bad pagination `from` parameter. */ + 400: unknown; + }; + }; + /** + * This will listen for new events related to a particular room and return + * them to the caller. This will block until an event is received, or until + * the `timeout` is reached. + * + * This API is the same as the normal `/events` endpoint, but can be + * called by users who have not joined the room. + * + * Note that the normal `/events` endpoint has been deprecated. This + * API will also be deprecated at some point, but its replacement is not + * yet known. + */ + peekEvents: { + parameters: { + query: { + /** + * The token to stream from. This token is either from a previous + * request to this API or from the initial sync API. + */ + from?: string; + /** The maximum time in milliseconds to wait for an event. */ + timeout?: number; + /** The room ID for which events should be returned. */ + room_id?: string; + }; + }; + responses: { + /** The events received, which may be none. */ + 200: { + schema: { + /** @description An array of events. */ + chunk?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token which correlates to the last value in `chunk`. This + * token should be used in the next request to `/events`. + */ + end?: string; + /** + * @description A token which correlates to the first value in `chunk`. This + * is usually the same token supplied to `from=`. + */ + start?: string; + }; + }; + /** Bad pagination `from` parameter. */ + 400: unknown; + }; + }; + /** + * Get a single event based on `event_id`. You must have permission to + * retrieve this event e.g. by being a member in the room for this event. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the + * [/rooms/{roomId}/event/{eventId}](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomideventeventid) API + * or the [/rooms/{roomId}/context/{eventId](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3roomsroomidcontexteventid) API. + */ + getOneEvent: { + parameters: { + path: { + /** The event ID to get. */ + eventId: string; + }; + }; + responses: { + /** The full event. */ + 200: { + schema: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + }; + }; + /** The event was not found or you do not have permission to read this event. */ + 404: unknown; + }; + }; + /** + * This returns the full state for this user, with an optional limit on the + * number of messages per room to return. + * + * This endpoint was deprecated in r0 of this specification. Clients + * should instead call the [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) + * endpoint with no `since` parameter. See + * the [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + initialSync: { + parameters: { + query: { + /** The maximum number of messages to return for each room. */ + limit?: number; + /** + * Whether to include rooms that the user has left. If `false` then + * only rooms that the user has been invited to or has joined are + * included. If set to `true` then rooms that the user has left are + * included as well. By default this is `false`. + */ + archived?: boolean; + }; + }; + responses: { + /** The user's current state. */ + 200: { + schema: { + /** @description The global private data created by this user. */ + account_data?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + /** + * @description A token which correlates to the end of the timelines returned. This + * token should be used with the `/events` endpoint to listen for new + * events. + */ + end: string; + /** @description A list of presence events. */ + presence: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + rooms: { + /** + * @description The private data that this user has attached to + * this room. + */ + account_data?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * InviteEvent + * @description The invite event if `membership` is `invite` + */ + invite?: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + }; + /** + * @description The user's membership state in this room. + * @enum {string} + */ + membership: "invite" | "join" | "leave" | "ban"; + /** + * PaginationChunk + * @description The pagination chunk for this room. + */ + messages?: { + /** + * @description If the user is a member of the room this will be a + * list of the most recent messages for this room. If + * the user has left the room this will be the + * messages that preceded them leaving. This array + * will consist of at most `limit` elements. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token which correlates to the end of `chunk`. + * Can be passed to + * [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + * to retrieve later events. + */ + end: string; + /** + * @description A token which correlates to the start of `chunk`. + * Can be passed to + * [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + * to retrieve earlier events. + * + * If no earlier events are available, this property may be omitted from + * the response. + */ + start?: string; + }; + /** @description The ID of this room. */ + room_id: string; + /** + * @description If the user is a member of the room this will be the + * current state of the room as a list of events. If the + * user has left the room this will be the state of the + * room when they left it. + */ + state?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description Whether this room is visible to the `/publicRooms` API + * or not." + * @enum {string} + */ + visibility?: "private" | "public"; + }[]; + }; + }; + /** There is no avatar URL for this user or this user does not exist. */ + 404: unknown; + }; + }; + /** + * *Note that this API takes either a room ID or alias, unlike* `/rooms/{roomId}/join`. + * + * This API starts a user participating in a particular room, if that user + * is allowed to participate in that room. After this call, the client is + * allowed to see all current state events in the room, and all subsequent + * events associated with the room until the user leaves the room. + * + * After a user has joined a room, the room will appear as an entry in the + * response of the [`/initialSync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3initialsync) + * and [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) APIs. + */ + joinRoom: { + parameters: { + path: { + /** The room identifier or alias to join. */ + roomIdOrAlias: string; + }; + query: { + /** + * The servers to attempt to join the room through. One of the servers + * must be participating in the room. + */ + server_name?: string[]; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + * @example Looking for support + */ + reason?: string; + /** + * @description If a `third_party_signed` was supplied, the homeserver must verify + * that it matches a pending `m.room.third_party_invite` event in the + * room, and perform key validity checking if required by the event. + */ + third_party_signed?: { + /** + * @description The Matrix ID of the invitee. + * @example @bob:example.org + */ + mxid: string; + /** + * @description The Matrix ID of the user who issued the invite. + * @example @alice:example.org + */ + sender: string; + /** + * Signatures + * @description A signatures object containing a signature of the entire signed object. + * @example { + * "example.org": { + * "ed25519:0": "some9signature" + * } + * } + */ + signatures: { [key: string]: { [key: string]: string } }; + /** + * @description The state key of the m.third_party_invite event. + * @example random8nonce + */ + token: string; + }; + }; + }; + }; + responses: { + /** + * The room has been joined. + * + * The joined room ID must be returned in the `room_id` field. + */ + 200: { + schema: { + /** @description The joined room ID. */ + room_id: string; + }; + }; + /** + * You do not have permission to join the room. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The room is invite-only and the user was not invited. + * - The user has been banned from the room. + * - The room is restricted and the user failed to satisfy any of the conditions. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** This API returns a list of the user's current rooms. */ + getJoinedRooms: { + responses: { + /** A list of the rooms the user is in. */ + 200: { + schema: { + /** @description The ID of each room in which the user has `joined` membership. */ + joined_rooms: string[]; + }; + }; + }; + }; + /** + * Gets a list of users who have updated their device identity keys since a + * previous sync token. + * + * The server should include in the results any users who: + * + * * currently share a room with the calling user (ie, both users have + * membership state `join`); *and* + * * added new device identity keys or removed an existing device with + * identity keys, between `from` and `to`. + */ + getKeysChanges: { + parameters: { + query: { + /** + * The desired start point of the list. Should be the `next_batch` field + * from a response to an earlier call to [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync). Users who have not + * uploaded new device identity keys since this point, nor deleted + * existing devices with identity keys since then, will be excluded + * from the results. + */ + from: string; + /** + * The desired end point of the list. Should be the `next_batch` + * field from a recent call to [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) - typically the most recent + * such call. This may be used by the server as a hint to check its + * caches are up to date. + */ + to: string; + }; + }; + responses: { + /** The list of users who updated their devices. */ + 200: { + schema: { + /** + * @description The Matrix User IDs of all users who updated their device + * identity keys. + * @example [ + * "@alice:example.com", + * "@bob:example.org" + * ] + */ + changed?: string[]; + /** + * @description The Matrix User IDs of all users who may have left all + * the end-to-end encrypted rooms they previously shared + * with the user. + * @example [ + * "@clara:example.com", + * "@doug:example.org" + * ] + */ + left?: string[]; + }; + }; + }; + }; + /** Claims one-time keys for use in pre-key messages. */ + claimKeys: { + parameters: { + body: { + /** Query defining the keys to be claimed */ + query: { + /** + * @description The keys to be claimed. A map from user ID, to a map from + * device ID to algorithm name. + * @example { + * "@alice:example.com": { + * "JLAFKJWSCS": "signed_curve25519" + * } + * } + */ + one_time_keys: { [key: string]: { [key: string]: string } }; + /** + * @description The time (in milliseconds) to wait when downloading keys from + * remote servers. 10 seconds is the recommended default. + * @example 10000 + */ + timeout?: number; + }; + }; + }; + responses: { + /** The claimed keys. */ + 200: { + schema: { + /** + * @description If any remote homeservers could not be reached, they are + * recorded here. The names of the properties are the names of + * the unreachable servers. + * + * If the homeserver could be reached, but the user or device + * was unknown, no failure is recorded. Instead, the corresponding + * user or device is missing from the `one_time_keys` result. + * @example {} + */ + failures?: { [key: string]: { [key: string]: unknown } }; + /** + * @description One-time keys for the queried devices. A map from user ID, to a + * map from devices to a map from `:` to the key object. + * + * See the [key algorithms](https://spec.matrix.org/v1.7/client-server-api/#key-algorithms) section for information + * on the Key Object format. + * + * If necessary, the claimed key might be a fallback key. Fallback + * keys 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" + * } + * } + * } + * } + * } + * } + */ + one_time_keys: { + [key: string]: { [key: string]: { [key: string]: unknown } }; + }; + }; + }; + }; + }; + /** + * Publishes cross-signing keys for the user. + * + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api). + */ + uploadCrossSigningKeys: { + parameters: { + body: { + /** The keys to be published. */ + keys: { + /** + * @description Additional authentication information for the + * user-interactive authentication API. + */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** @description Optional. The user\'s master key. */ + master_key?: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + /** + * @description Optional. The user\'s self-signing key. Must be signed by + * the accompanying master key, or by the user\'s most recently + * uploaded master key if no master key is included in the + * request. + */ + self_signing_key?: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + /** + * @description Optional. The user\'s user-signing key. Must be signed by + * the accompanying master key, or by the user\'s most recently + * uploaded master key if no master key is included in the + * request. + */ + user_signing_key?: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + }; + }; + }; + responses: { + /** The provided keys were successfully uploaded. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The input was invalid in some way. This can include one of the + * following error codes: + * + * * `M_INVALID_SIGNATURE`: For example, the self-signing or + * user-signing key had an incorrect signature. + * * `M_MISSING_PARAM`: No master key is available. + */ + 400: { + schema: { [key: string]: unknown }; + }; + /** + * The public key of one of the keys is the same as one of the user\'s + * device IDs, or the request is not authorized for any other reason. + */ + 403: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** Returns the current devices and identity keys for the given users. */ + queryKeys: { + parameters: { + body: { + /** Query defining the keys to be downloaded */ + query: { + /** + * @description The keys to be downloaded. A map from user ID, to a list of + * device IDs, or to an empty list to indicate all devices for the + * corresponding user. + * @example { + * "@alice:example.com": [] + * } + */ + device_keys: { [key: string]: string[] }; + /** + * @description The time (in milliseconds) to wait when downloading keys from + * remote servers. 10 seconds is the recommended default. + * @example 10000 + */ + timeout?: number; + }; + }; + }; + responses: { + /** The device information */ + 200: { + schema: { + /** + * @description Information on the queried devices. A map from user ID, to a + * map from device ID to device information. For each device, + * the information returned will be the same as uploaded via + * `/keys/upload`, with the addition of an `unsigned` + * property. + * @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" + * } + * } + * } + */ + device_keys?: { + [key: string]: { + [key: string]: { + /** + * @description The encryption algorithms supported by this device. + * @example [ + * "m.olm.v1.curve25519-aes-sha2", + * "m.megolm.v1.aes-sha2" + * ] + */ + algorithms: string[]; + /** + * @description The ID of the device these keys belong to. Must match the device ID used + * when logging in. + * @example JLAFKJWSCS + */ + device_id: string; + /** + * @description Public identity keys. The names of the properties should be in the + * format `:`. The keys themselves should be + * encoded as specified by the key algorithm. + * @example { + * "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + * "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures for the device key object. A map from user ID, to a map from + * `:` to the signature. + * + * The signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * @example { + * "@alice:example.com": { + * "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + * } + * } + */ + signatures: { [key: string]: { [key: string]: string } }; + /** + * @description The ID of the user the device belongs to. Must match the user ID used + * when logging in. + * @example @alice:example.com + */ + user_id: string; + } & { + /** + * UnsignedDeviceInfo + * @description Additional data added to the device key information + * by intermediate servers, and not covered by the + * signatures. + */ + unsigned?: { + /** @description The display name which the user set on the device. */ + device_display_name?: string; + }; + }; + }; + }; + /** + * @description If any remote homeservers could not be reached, they are + * recorded here. The names of the properties are the names of + * the unreachable servers. + * + * If the homeserver could be reached, but the user or device + * was unknown, no failure is recorded. Instead, the corresponding + * user or device is missing from the `device_keys` result. + * @example {} + */ + failures?: { [key: string]: { [key: string]: unknown } }; + /** + * @description Information on the master cross-signing keys of the queried users. + * A map from user ID, to master key information. For each key, the + * information returned will be the same as uploaded via + * `/keys/device_signing/upload`, along with the signatures + * uploaded via `/keys/signatures/upload` that the requesting user + * is allowed to see. + * @example { + * "@alice:example.com": { + * "keys": { + * "ed25519:base64+master+public+key": "base64+master+public+key" + * }, + * "usage": [ + * "master" + * ], + * "user_id": "@alice:example.com" + * } + * } + */ + master_keys?: { + [key: string]: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + }; + /** + * @description Information on the self-signing keys of the queried users. A map + * from user ID, to self-signing key information. For each key, the + * information returned will be the same as uploaded via + * `/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" + * } + * } + */ + self_signing_keys?: { + [key: string]: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + }; + /** + * @description Information on the user-signing key of the user making the + * request, if they queried their own device information. A map + * from user ID, to user-signing key information. The + * information returned will be the same as uploaded via + * `/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" + * } + * } + */ + user_signing_keys?: { + [key: string]: { + /** + * @description The public key. The object must have exactly one property, whose name is + * in the form `:`, and whose value + * is the unpadded base64 public key. + * @example { + * "ed25519:alice+base64+public+key": "alice+base64+public+key" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures of the key, calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * Optional for the master key. Other keys must be signed by the + * user\'s master key. + * @example { + * "@alice:example.com": { + * "ed25519:alice+base64+master+key": "signature+of+key" + * } + * } + */ + signatures?: { [key: string]: unknown }; + /** @description What the key is used for. */ + usage: ("master" | "self_signing" | "user_signing")[]; + /** + * @description The ID of the user the key belongs to. + * @example @alice:example.com + */ + user_id: string; + }; + }; + }; + }; + }; + }; + /** + * Publishes cross-signing signatures for the user. + * + * The request body is a map from user ID to key ID to signed JSON object. + * The signed JSON object must match the key previously uploaded or + * retrieved for the given key ID, with the exception of the `signatures` + * property, which contains the new signature(s) to add. + */ + uploadCrossSigningSignatures: { + parameters: { + body: { + /** + * A map from user ID to key ID to signed JSON objects containing the + * signatures to be published. + */ + signatures: { + [key: string]: { [key: string]: { [key: string]: unknown } }; + }; + }; + }; + responses: { + /** The provided signatures were processed. */ + 200: { + schema: { + /** + * @description A map from user ID to key ID to an error for any signatures + * that failed. If a signature was invalid, the `errcode` will + * be set to `M_INVALID_SIGNATURE`. + * @example { + * "@alice:example.com": { + * "HIJKLMN": { + * "errcode": "M_INVALID_SIGNATURE", + * "error": "Invalid signature" + * } + * } + * } + */ + failures?: { + [key: string]: { [key: string]: { [key: string]: unknown } }; + }; + }; + }; + }; + }; + /** Publishes end-to-end encryption keys for the device. */ + uploadKeys: { + parameters: { + body: { + /** The keys to be published */ + keys: { + /** + * @description Identity keys for the device. May be absent if no new + * identity keys are required. + */ + device_keys?: { + /** + * @description The encryption algorithms supported by this device. + * @example [ + * "m.olm.v1.curve25519-aes-sha2", + * "m.megolm.v1.aes-sha2" + * ] + */ + algorithms: string[]; + /** + * @description The ID of the device these keys belong to. Must match the device ID used + * when logging in. + * @example JLAFKJWSCS + */ + device_id: string; + /** + * @description Public identity keys. The names of the properties should be in the + * format `:`. The keys themselves should be + * encoded as specified by the key algorithm. + * @example { + * "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI", + * "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI" + * } + */ + keys: { [key: string]: string }; + /** + * Signatures + * @description Signatures for the device key object. A map from user ID, to a map from + * `:` to the signature. + * + * The signature is calculated using the process described at [Signing JSON](https://spec.matrix.org/v1.7/appendices/#signing-json). + * @example { + * "@alice:example.com": { + * "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA" + * } + * } + */ + signatures: { [key: string]: { [key: string]: string } }; + /** + * @description The ID of the user the device belongs to. Must match the user ID used + * when logging in. + * @example @alice:example.com + */ + user_id: string; + }; + /** + * OneTimeKeys + * @description The public key which should be used if the device's one-time keys + * are exhausted. The fallback key is not deleted once used, but should + * be replaced when additional one-time keys are being uploaded. The + * server will notify the client of the fallback key being used through + * `/sync`. + * + * There can only be at most one key per algorithm uploaded, and the server + * will only persist one key per algorithm. + * + * When uploading a signed key, an additional `fallback: true` key should + * be included to denote that the key is a fallback key. + * + * May be absent if a new fallback key is not required. + * @example { + * "curve25519:AAAAAG": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", + * "signed_curve25519:AAAAGj": { + * "fallback": true, + * "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + * "signatures": { + * "@alice:example.com": { + * "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + * } + * } + * } + * } + */ + fallback_keys?: { [key: string]: unknown }; + /** + * OneTimeKeys + * @description One-time public keys for "pre-key" messages. The names of + * the properties should be in the format + * `:`. The format of the key is determined + * by the [key algorithm](https://spec.matrix.org/v1.7/client-server-api/#key-algorithms). + * + * May be absent if no new one-time keys are required. + * @example { + * "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8", + * "signed_curve25519:AAAAHQ": { + * "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw", + * "signatures": { + * "@alice:example.com": { + * "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA" + * } + * } + * }, + * "signed_curve25519:AAAAHg": { + * "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs", + * "signatures": { + * "@alice:example.com": { + * "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw" + * } + * } + * } + * } + */ + one_time_keys?: { [key: string]: unknown }; + }; + }; + }; + responses: { + /** The provided keys were successfully uploaded. */ + 200: { + schema: { + /** + * @description For each key algorithm, the number of unclaimed one-time keys + * of that type currently held on the server for this device. + * If an algorithm is not listed, the count for that algorithm + * is to be assumed zero. + * @example { + * "curve25519": 10, + * "signed_curve25519": 20 + * } + */ + one_time_key_counts: { [key: string]: number }; + }; + }; + }; + }; + /** + * *Note that this API takes either a room ID or alias, unlike other membership APIs.* + * + * This API "knocks" on the room to ask for permission to join, if the user + * is allowed to knock on the room. Acceptance of the knock happens out of + * band from this API, meaning that the client will have to watch for updates + * regarding the acceptance/rejection of the knock. + * + * If the room history settings allow, the user will still be able to see + * history of the room while being in the "knock" state. The user will have + * to accept the invitation to join the room (acceptance of knock) to see + * messages reliably. See the `/join` endpoints for more information about + * history visibility to the user. + * + * The knock will appear as an entry in the response of the + * [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) API. + */ + knockRoom: { + parameters: { + path: { + /** The room identifier or alias to knock upon. */ + roomIdOrAlias: string; + }; + query: { + /** + * The servers to attempt to knock on the room through. One of the servers + * must be participating in the room. + */ + server_name?: string[]; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + * @example Looking for support + */ + reason?: string; + }; + }; + }; + responses: { + /** + * The room has been knocked upon. + * + * The knocked room ID must be returned in the `room_id` field. + */ + 200: { + schema: { + /** @description The knocked room ID. */ + room_id: string; + }; + }; + /** + * You do not have permission to knock on the room. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The room is not set up for knocking. + * - The user has been banned from the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The room could not be found or resolved to a room ID. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Gets the homeserver's supported login types to authenticate users. Clients + * should pick one of these and supply it as the `type` when logging in. + */ + getLoginFlows: { + responses: { + /** The login types the homeserver supports */ + 200: { + schema: { + /** @description The homeserver's supported login types */ + flows?: { + /** + * @description If `type` is `m.login.token`, an optional field to indicate + * to the unauthenticated client that the homeserver supports + * the [`POST /login/get_token`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv1loginget_token) + * endpoint. Note that supporting the endpoint does not + * necessarily indicate that the user attempting to log in will + * be able to generate such a token. + */ + get_login_token?: boolean; + /** + * @description The login type. This is supplied as the `type` when + * logging in. + */ + type: string; + }[]; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Authenticates the user, and issues an access token they can + * use to authorize themself in subsequent requests. + * + * If the client does not supply a `device_id`, the server must + * auto-generate one. + * + * The returned access token must be associated with the `device_id` + * supplied by the client or generated by the server. The server may + * invalidate any access token previously associated with that device. See + * [Relationship between access tokens and devices](https://spec.matrix.org/v1.7/client-server-api/#relationship-between-access-tokens-and-devices). + */ + login: { + parameters: { + body: { + body: { + /** @description Third-party identifier for the user. Deprecated in favour of `identifier`. */ + address?: string; + /** + * @description ID of the client device. If this does not correspond to a + * known client device, a new device will be created. The given + * device ID must not be the same as a + * [cross-signing](https://spec.matrix.org/v1.7/client-server-api/#cross-signing) key ID. + * The server will auto-generate a device_id + * if this is not specified. + */ + device_id?: string; + /** + * User identifier + * @description Identification information for a user + */ + identifier?: { + /** @description The type of identification. See [Identifier types](https://spec.matrix.org/v1.7/client-server-api/#identifier-types) for supported values and additional property descriptions. */ + type: string; + } & { [key: string]: unknown }; + /** + * @description A display name to assign to the newly-created device. Ignored + * if `device_id` corresponds to a known device. + */ + initial_device_display_name?: string; + /** @description When logging in using a third-party identifier, the medium of the identifier. Must be 'email'. Deprecated in favour of `identifier`. */ + medium?: string; + /** + * @description Required when `type` is `m.login.password`. The user's + * password. + */ + password?: string; + /** @description If true, the client supports refresh tokens. */ + refresh_token?: boolean; + /** @description Required when `type` is `m.login.token`. Part of Token-based login. */ + token?: string; + /** + * @description The login type being used. + * @enum {string} + */ + type: "m.login.password" | "m.login.token"; + /** @description The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of `identifier`. */ + user?: string; + }; + }; + }; + responses: { + /** The user has been authenticated. */ + 200: { + schema: { + /** + * @description An access token for the account. + * This access token can then be used to authorize other requests. + */ + access_token: string; + /** + * @description ID of the logged-in device. Will be the same as the + * corresponding parameter in the request, if one was specified. + */ + device_id: string; + /** + * @description The lifetime of the access token, in milliseconds. Once + * the access token has expired a new access token can be + * obtained by using the provided refresh token. If no + * refresh token is provided, the client will need to re-log in + * to obtain a new access token. If not given, the client can + * assume that the access token will not expire. + */ + expires_in_ms?: number; + /** + * @description The server_name of the homeserver on which the account has + * been registered. + * + * **Deprecated**. Clients should extract the server_name from + * `user_id` (by splitting at the first colon) if they require + * it. Note also that `homeserver` is not spelt this way. + */ + home_server?: string; + /** + * @description A refresh token for the account. This token can be used to + * obtain a new access token when it expires by calling the + * `/refresh` endpoint. + */ + refresh_token?: string; + /** @description The fully-qualified Matrix ID for the account. */ + user_id: string; + /** + * @description Optional client configuration provided by the server. If present, + * clients SHOULD use the provided object to reconfigure themselves, + * optionally validating the URLs within. This object takes the same + * form as the one returned from .well-known autodiscovery. + */ + well_known?: { + /** + * Homeserver Information + * @description Used by clients to discover homeserver information. + */ + "m.homeserver": { + /** + * Format: uri + * @description The base URL for the homeserver for client-server connections. + * @example https://matrix.example.com + */ + base_url: string; + }; + /** + * Identity Server Information + * @description Used by clients to discover identity server information. + */ + "m.identity_server"?: { + /** + * Format: uri + * @description The base URL for the identity server for client-server connections. + * @example https://identity.example.com + */ + base_url: string; + }; + } & { [key: string]: { [key: string]: unknown } }; + }; + }; + /** Part of the request was invalid. For example, the login type may not be recognised. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The login attempt failed. This can include one of the following error codes: + * * `M_FORBIDDEN`: The provided authentication data was incorrect + * or the requested device ID is the same as a cross-signing key + * ID. + * * `M_USER_DEACTIVATED`: The user has been deactivated. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * A web-based Matrix client should instruct the user's browser to + * navigate to this endpoint in order to log in via SSO. + * + * The server MUST respond with an HTTP redirect to the SSO interface, + * or present a page which lets the user select an IdP to continue + * with in the event multiple are supported by the server. + */ + redirectToSSO: { + parameters: { + query: { + /** + * URI to which the user will be redirected after the homeserver has + * authenticated the user with SSO. + */ + redirectUrl: string; + }; + }; + responses: { + /** A redirect to the SSO interface. */ + 302: never; + }; + }; + /** + * This endpoint is the same as `/login/sso/redirect`, though with an + * IdP ID from the original `identity_providers` array to inform the + * server of which IdP the client/user would like to continue with. + * + * The server MUST respond with an HTTP redirect to the SSO interface + * for that IdP. + */ + redirectToIdP: { + parameters: { + path: { + /** + * The `id` of the IdP from the `m.login.sso` `identity_providers` + * array denoting the user's selection. + */ + idpId: string; + }; + query: { + /** + * URI to which the user will be redirected after the homeserver has + * authenticated the user with SSO. + */ + redirectUrl: string; + }; + }; + responses: { + /** A redirect to the SSO interface. */ + 302: never; + /** + * The IdP ID was not recognized by the server. The server is encouraged + * to provide a user-friendly page explaining the error given the user + * will be navigated to it. + */ + 404: unknown; + }; + }; + /** + * Invalidates an existing access token, so that it can no longer be used for + * authorization. The device associated with the access token is also deleted. + * [Device keys](https://spec.matrix.org/v1.7/client-server-api/#device-keys) for the device are deleted alongside the device. + */ + logout: { + responses: { + /** The access token used in the request was successfully invalidated. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** + * Invalidates all access tokens for a user, so that they can no longer be used for + * authorization. This includes the access token that made this request. All devices + * for the user are also deleted. [Device keys](https://spec.matrix.org/v1.7/client-server-api/#device-keys) for the device are + * deleted alongside the device. + * + * This endpoint does not use the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api) because + * User-Interactive Authentication is designed to protect against attacks where the + * someone gets hold of a single access token then takes over the account. This + * endpoint invalidates all access tokens for the user, including the token used in + * the request, and therefore the attacker is unable to take over the account in + * this way. + */ + logout_all: { + responses: { + /** The user's access tokens were successfully invalidated. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** + * This API is used to paginate through the list of events that the + * user has been, or would have been notified about. + */ + getNotifications: { + parameters: { + query: { + /** + * Pagination token to continue from. This should be the `next_token` + * returned from an earlier call to this endpoint. + */ + from?: string; + /** Limit on the number of events to return in this request. */ + limit?: number; + /** + * Allows basic filtering of events returned. Supply `highlight` + * to return only events where the notification had the highlight + * tweak set. + */ + only?: string; + }; + }; + responses: { + /** A batch of events is being returned */ + 200: { + schema: { + /** + * @description The token to supply in the `from` param of the next + * `/notifications` request in order to request more + * events. If this is absent, there are no more results. + */ + next_token?: string; + /** @description The list of events that triggered notifications. */ + notifications: { + /** + * @description The action(s) to perform when the conditions for this rule are met. + * See [Push Rules: API](https://spec.matrix.org/v1.7/client-server-api/#push-rules-api). + */ + actions: unknown[]; + /** + * Event + * @description The Event object for the event that triggered the notification. + */ + event: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + }; + /** @description The profile tag of the rule that matched this event. */ + profile_tag?: string; + /** + * @description Indicates whether the user has sent a read receipt indicating + * that they have read this message. + */ + read: boolean; + /** @description The ID of the room in which the event was posted. */ + room_id: string; + /** + * Format: int64 + * @description The unix timestamp at which the event notification was sent, + * in milliseconds. + */ + ts: number; + }[]; + }; + }; + }; + }; + /** Get the given user's presence state. */ + getPresence: { + parameters: { + path: { + /** The user whose presence state to get. */ + userId: string; + }; + }; + responses: { + /** The presence state for this user. */ + 200: { + schema: { + /** @description Whether the user is currently active */ + currently_active?: boolean; + /** + * @description The length of time in milliseconds since an action was performed + * by this user. + */ + last_active_ago?: number; + /** + * @description This user's presence. + * @enum {string} + */ + presence: "online" | "offline" | "unavailable"; + /** @description The state message for this user if one was set. */ + status_msg?: unknown; + }; + }; + /** You are not allowed to see this user's presence status. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * There is no presence state for this user. This user may not exist or + * isn't exposing presence information to you. + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API sets the given user's presence state. When setting the status, + * the activity time is updated to reflect that activity; the client does + * not need to specify the `last_active_ago` field. You cannot set the + * presence state of another user. + */ + setPresence: { + parameters: { + path: { + /** The user whose presence state to update. */ + userId: string; + }; + body: { + /** The updated presence state. */ + presenceState: { + /** + * @description The new presence state. + * @enum {string} + */ + presence: "online" | "offline" | "unavailable"; + /** @description The status message to attach to this state. */ + status_msg?: string; + }; + }; + }; + responses: { + /** The new presence state was set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get the combined profile information for this user. This API may be used + * to fetch the user's own profile information or other users; either + * locally or on remote homeservers. This API may return keys which are not + * limited to `displayname` or `avatar_url`. + */ + getUserProfile: { + parameters: { + path: { + /** The user whose profile information to get. */ + userId: string; + }; + }; + responses: { + /** The profile information for this user. */ + 200: { + schema: { + /** + * Format: uri + * @description The user's avatar URL if they have set one, otherwise not present. + */ + avatar_url?: string; + /** @description The user's display name if they have set one, otherwise not present. */ + displayname?: string; + }; + }; + /** The server is unwilling to disclose whether the user exists and/or has profile information. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** There is no profile information for this user or this user does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Get the user's avatar URL. This API may be used to fetch the user's + * own avatar URL or to query the URL of other users; either locally or + * on remote homeservers. + */ + getAvatarUrl: { + parameters: { + path: { + /** The user whose avatar URL to get. */ + userId: string; + }; + }; + responses: { + /** The avatar URL for this user. */ + 200: { + schema: { + /** + * Format: uri + * @description The user's avatar URL if they have set one, otherwise not present. + */ + avatar_url?: string; + }; + }; + /** There is no avatar URL for this user or this user does not exist. */ + 404: unknown; + }; + }; + /** + * This API sets the given user's avatar URL. You must have permission to + * set this user's avatar URL, e.g. you need to have their `access_token`. + */ + setAvatarUrl: { + parameters: { + path: { + /** The user whose avatar URL to set. */ + userId: string; + }; + body: { + /** The new avatar information. */ + avatar_url: { + /** + * Format: uri + * @description The new avatar URL for this user. + */ + avatar_url?: string; + }; + }; + }; + responses: { + /** The avatar URL was set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get the user's display name. This API may be used to fetch the user's + * own displayname or to query the name of other users; either locally or + * on remote homeservers. + */ + getDisplayName: { + parameters: { + path: { + /** The user whose display name to get. */ + userId: string; + }; + }; + responses: { + /** The display name for this user. */ + 200: { + schema: { + /** @description The user's display name if they have set one, otherwise not present. */ + displayname?: string; + }; + }; + /** There is no display name for this user or this user does not exist. */ + 404: unknown; + }; + }; + /** + * This API sets the given user's display name. You must have permission to + * set this user's display name, e.g. you need to have their `access_token`. + */ + setDisplayName: { + parameters: { + path: { + /** The user whose display name to set. */ + userId: string; + }; + body: { + /** The new display name information. */ + displayName: { + /** @description The new display name for this user. */ + displayname?: string; + }; + }; + }; + responses: { + /** The display name was set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Lists the public rooms on the server. + * + * This API returns paginated responses. The rooms are ordered by the number + * of joined members, with the largest rooms first. + */ + getPublicRooms: { + parameters: { + query: { + /** Limit the number of results returned. */ + limit?: number; + /** + * A pagination token from a previous request, allowing clients to + * get the next (or previous) batch of rooms. + * The direction of pagination is specified solely by which token + * is supplied, rather than via an explicit flag. + */ + since?: string; + /** + * The server to fetch the public room lists from. Defaults to the + * local server. + */ + server?: string; + }; + }; + responses: { + /** A list of the rooms on the server. */ + 200: { + schema: { + /** @description A paginated chunk of public rooms. */ + chunk: ({ + /** + * Format: uri + * @description The URL for the room's avatar, if one is set. + * @example mxc://example.org/abcdef + */ + avatar_url?: string; + /** + * @description The canonical alias of the room, if any. + * @example #general:example.org + */ + canonical_alias?: string; + /** + * @description Whether guest users may join the room and participate in it. + * If they can, they will be subject to ordinary power level + * rules like any other user. + * @example true + */ + guest_can_join: boolean; + /** + * @description The room's join rule. When not present, the room is assumed to + * be `public`. + * @example public + */ + join_rule?: string; + /** + * @description The name of the room, if any. + * @example General Chat + */ + name?: string; + /** + * @description The number of members joined to the room. + * @example 42 + */ + num_joined_members: number; + /** + * @description The ID of the room. + * @example !abcdefg:example.org + */ + room_id: string; + /** @description The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.7/client-server-api/#mroomcreate)), if any. */ + room_type?: string; + /** + * @description The topic of the room, if any. + * @example All things general + */ + topic?: string; + /** + * @description Whether the room may be viewed by guest users without joining. + * @example false + */ + world_readable: boolean; + } & { + /** + * @description The room's join rule. When not present, the room is assumed to + * be `public`. Note that rooms with `invite` join rules are not + * expected here, but rooms with `knock` rules are given their + * near-public nature. + * @example public + */ + join_rule?: string; + })[]; + /** + * @description A pagination token for the response. The absence of this token + * means there are no more results to fetch and the client should + * stop paginating. + */ + next_batch?: string; + /** + * @description A pagination token that allows fetching previous results. The + * absence of this token means there are no results before this + * batch, i.e. this is the first batch. + */ + prev_batch?: string; + /** + * @description An estimate on the total number of public rooms, if the + * server has an estimate. + */ + total_room_count_estimate?: number; + }; + }; + }; + }; + /** + * Lists the public rooms on the server, with optional filter. + * + * This API returns paginated responses. The rooms are ordered by the number + * of joined members, with the largest rooms first. + */ + queryPublicRooms: { + parameters: { + query: { + /** + * The server to fetch the public room lists from. Defaults to the + * local server. + */ + server?: string; + }; + body: { + /** Options for which rooms to return. */ + body: { + /** + * Filter + * @description Filter to apply to the results. + */ + filter?: { + /** + * @description An optional string to search for in the room metadata, e.g. name, + * topic, canonical alias, etc. + */ + generic_search_term?: string; + /** + * @description An optional list of [room types](https://spec.matrix.org/v1.7/client-server-api/#types) to search + * for. To include rooms without a room type, specify `null` within this + * list. When not specified, all applicable rooms (regardless of type) + * are returned. + */ + room_types?: string[]; + }; + /** + * @description Whether or not to include all known networks/protocols from + * application services on the homeserver. Defaults to false. + * @example false + */ + include_all_networks?: boolean; + /** @description Limit the number of results returned. */ + limit?: number; + /** + * @description A pagination token from a previous request, allowing clients + * to get the next (or previous) batch of rooms. The direction + * of pagination is specified solely by which token is supplied, + * rather than via an explicit flag. + */ + since?: string; + /** + * @description The specific third-party network/protocol to request from the + * homeserver. Can only be used if `include_all_networks` is false. + * @example irc + */ + third_party_instance_id?: string; + }; + }; + }; + responses: { + /** A list of the rooms on the server. */ + 200: { + schema: { + /** @description A paginated chunk of public rooms. */ + chunk: ({ + /** + * Format: uri + * @description The URL for the room's avatar, if one is set. + * @example mxc://example.org/abcdef + */ + avatar_url?: string; + /** + * @description The canonical alias of the room, if any. + * @example #general:example.org + */ + canonical_alias?: string; + /** + * @description Whether guest users may join the room and participate in it. + * If they can, they will be subject to ordinary power level + * rules like any other user. + * @example true + */ + guest_can_join: boolean; + /** + * @description The room's join rule. When not present, the room is assumed to + * be `public`. + * @example public + */ + join_rule?: string; + /** + * @description The name of the room, if any. + * @example General Chat + */ + name?: string; + /** + * @description The number of members joined to the room. + * @example 42 + */ + num_joined_members: number; + /** + * @description The ID of the room. + * @example !abcdefg:example.org + */ + room_id: string; + /** @description The `type` of room (from [`m.room.create`](https://spec.matrix.org/v1.7/client-server-api/#mroomcreate)), if any. */ + room_type?: string; + /** + * @description The topic of the room, if any. + * @example All things general + */ + topic?: string; + /** + * @description Whether the room may be viewed by guest users without joining. + * @example false + */ + world_readable: boolean; + } & { + /** + * @description The room's join rule. When not present, the room is assumed to + * be `public`. Note that rooms with `invite` join rules are not + * expected here, but rooms with `knock` rules are given their + * near-public nature. + * @example public + */ + join_rule?: string; + })[]; + /** + * @description A pagination token for the response. The absence of this token + * means there are no more results to fetch and the client should + * stop paginating. + */ + next_batch?: string; + /** + * @description A pagination token that allows fetching previous results. The + * absence of this token means there are no results before this + * batch, i.e. this is the first batch. + */ + prev_batch?: string; + /** + * @description An estimate on the total number of public rooms, if the + * server has an estimate. + */ + total_room_count_estimate?: number; + }; + }; + }; + }; + /** Gets all currently active pushers for the authenticated user. */ + getPushers: { + responses: { + /** The pushers for this user. */ + 200: { + schema: { + /** + * Pushers + * @description An array containing the current pushers for the user + */ + pushers?: { + /** + * @description A string that will allow the user to identify what application + * owns this pusher. + */ + app_display_name: string; + /** + * @description This is a reverse-DNS style identifier for the application. + * Max length, 64 chars. + */ + app_id: string; + /** + * PusherData + * @description A dictionary of information for the pusher implementation + * itself. + */ + data: { + /** + * @description The format to use when sending notifications to the Push + * Gateway. + */ + format?: string; + /** + * Format: uri + * @description Required if `kind` is `http`. The URL to use to send + * notifications to. + */ + url?: string; + }; + /** + * @description A string that will allow the user to identify what device owns + * this pusher. + */ + device_display_name: string; + /** + * @description The kind of pusher. `"http"` is a pusher that + * sends HTTP pokes. + */ + kind: string; + /** + * @description The preferred language for receiving notifications (e.g. 'en' + * or 'en-US') + */ + lang: string; + /** + * @description This string determines which set of device specific rules this + * pusher executes. + */ + profile_tag?: string; + /** + * @description This is a unique identifier for this pusher. See `/set` for + * more detail. + * Max length, 512 bytes. + */ + pushkey: string; + }[]; + }; + }; + }; + }; + /** + * This endpoint allows the creation, modification and deletion of [pushers](https://spec.matrix.org/v1.7/client-server-api/#push-notifications) + * for this user ID. The behaviour of this endpoint varies depending on the + * values in the JSON body. + * + * If `kind` is not `null`, the pusher with this `app_id` and `pushkey` + * for this user is updated, or it is created if it doesn't exist. If + * `kind` is `null`, the pusher with this `app_id` and `pushkey` for this + * user is deleted. + */ + postPusher: { + parameters: { + body: { + /** The pusher information. */ + pusher: { + /** + * @description Required if `kind` is not `null`. A string that will allow the + * user to identify what application owns this pusher. + */ + app_display_name?: string; + /** + * @description This is a reverse-DNS style identifier for the application. + * It is recommended that this end with the platform, such that + * different platform versions get different app identifiers. + * Max length, 64 chars. + * + * If the `kind` is `"email"`, this is `"m.email"`. + */ + app_id: string; + /** + * @description If true, the homeserver should add another pusher with the + * given pushkey and App ID in addition to any others with + * different user IDs. Otherwise, the homeserver must remove any + * other pushers with the same App ID and pushkey for different + * users. The default is `false`. + */ + append?: boolean; + /** + * PusherData + * @description Required if `kind` is not `null`. A dictionary of information + * for the pusher implementation itself. If `kind` is `http`, + * this should contain `url` which is the URL to use to send + * notifications to. + */ + data?: { + /** + * @description The format to send notifications in to Push Gateways if the + * `kind` is `http`. The details about what fields the + * homeserver should send to the push gateway are defined in the + * [Push Gateway Specification](https://spec.matrix.org/v1.7/push-gateway-api/). Currently the only format + * available is 'event_id_only'. + */ + format?: string; + /** + * Format: uri + * @description Required if `kind` is `http`. The URL to use to send + * notifications to. MUST be an HTTPS URL with a path of + * `/_matrix/push/v1/notify`. + * @example https://push-gateway.location.here/_matrix/push/v1/notify + */ + url?: string; + }; + /** + * @description Required if `kind` is not `null`. A string that will allow the + * user to identify what device owns this pusher. + */ + device_display_name?: string; + /** + * @description The kind of pusher to configure. `"http"` makes a pusher that + * sends HTTP pokes. `"email"` makes a pusher that emails the + * user with unread notifications. `null` deletes the pusher. + */ + kind: unknown; + /** + * @description Required if `kind` is not `null`. The preferred language for + * receiving notifications (e.g. 'en' or 'en-US'). + */ + lang?: string; + /** + * @description This string determines which set of device specific rules this + * pusher executes. + */ + profile_tag?: string; + /** + * @description This is a unique identifier for this pusher. The value you + * should use for this is the routing or destination address + * information for the notification, for example, the APNS token + * for APNS or the Registration ID for GCM. If your notification + * client has no such concept, use any unique identifier. + * Max length, 512 bytes. + * + * If the `kind` is `"email"`, this is the email address to + * send notifications to. + */ + pushkey: string; + }; + }; + }; + responses: { + /** The pusher was set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** One or more of the pusher values were invalid. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Retrieve all push rulesets for this user. Clients can "drill-down" on + * the rulesets by suffixing a `scope` to this path e.g. + * `/pushrules/global/`. This will return a subset of this data under the + * specified key e.g. the `global` key. + */ + getPushRules: { + responses: { + /** All the push rulesets for this user. */ + 200: { + schema: { + /** + * Ruleset + * @description The global ruleset. + */ + global: { + content?: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }[]; + override?: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }[]; + room?: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }[]; + sender?: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }[]; + underride?: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }[]; + }; + }; + }; + }; + }; + /** Retrieve a single specified push rule. */ + getPushRule: { + parameters: { + path: { + /** `global` to specify global rules. */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + }; + responses: { + /** + * The specific push rule. This will also include keys specific to the + * rule itself such as the rule's `actions` and `conditions` if set. + */ + 200: { + schema: { + /** @description The actions to perform when this rule is matched. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a rule to be + * applied to an event. A rule with no conditions always matches. Only + * applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Whether this is a default rule, or has been set explicitly. */ + default: boolean; + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + /** + * @description The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) to match against. + * Only applicable to `content` rules. + */ + pattern?: string; + /** @description The ID of this rule. */ + rule_id: string; + }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This endpoint allows the creation and modification of user defined push + * rules. + * + * If a rule with the same `rule_id` already exists among rules of the same + * kind, it is updated with the new parameters, otherwise a new rule is + * created. + * + * If both `after` and `before` are provided, the new or updated rule must + * be the next most important rule with respect to the rule identified by + * `before`. + * + * If neither `after` nor `before` are provided and the rule is created, it + * should be added as the most important user defined rule among rules of + * the same kind. + * + * When creating push rules, they MUST be enabled by default. + */ + setPushRule: { + parameters: { + path: { + /** `global` to specify global rules. */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** + * The identifier for the rule. If the string starts with a dot ("."), + * the request MUST be rejected as this is reserved for server-default + * rules. Slashes ("/") and backslashes ("\\") are also not allowed. + */ + ruleId: string; + }; + query: { + /** + * Use 'before' with a `rule_id` as its value to make the new rule the + * next-most important rule with respect to the given user defined rule. + * It is not possible to add a rule relative to a predefined server rule. + */ + before?: string; + /** + * This makes the new rule the next-less important rule relative to the + * given user defined rule. It is not possible to add a rule relative + * to a predefined server rule. + */ + after?: string; + }; + body: { + /** + * The push rule data. Additional top-level keys may be present depending + * on the parameters for the rule `kind`. + */ + pushrule: { + /** @description The action(s) to perform when the conditions for this rule are met. */ + actions: unknown[]; + /** + * @description The conditions that must hold true for an event in order for a + * rule to be applied to an event. A rule with no conditions + * always matches. Only applicable to `underride` and `override` rules. + */ + conditions?: { + /** + * @description Required for `room_member_count` conditions. A decimal integer + * optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches + * rooms where the member count is strictly less than the given number and + * so forth. If no prefix is present, this parameter defaults to ==. + */ + is?: string; + /** + * @description Required for `event_match` conditions. The dot-separated field of the + * event to match. + * + * Required for `sender_notification_permission` conditions. The field in + * the power level event the user needs a minimum power level for. Fields + * must be specified under the `notifications` property in the power level + * event's `content`. + */ + key?: string; + /** + * @description The kind of condition to apply. See [conditions](https://spec.matrix.org/v1.7/client-server-api/#conditions) for + * more information on the allowed kinds and how they work. + */ + kind: string; + /** + * @description Required for `event_match` conditions. The [glob-style pattern](https://spec.matrix.org/v1.7/appendices#glob-style-matching) + * to match against. + */ + pattern?: string; + }[]; + /** @description Only applicable to `content` rules. The glob-style pattern to match against. */ + pattern?: string; + }; + }; + }; + responses: { + /** The push rule was created/updated. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** There was a problem configuring this push rule. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The push rule does not exist (when updating a push rule). */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** This endpoint removes the push rule defined in the path. */ + deletePushRule: { + parameters: { + path: { + /** `global` to specify global rules. */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + }; + responses: { + /** The push rule was deleted. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** This endpoint get the actions for the specified push rule. */ + getPushRuleActions: { + parameters: { + path: { + /** + * Either `global` or `device/` to specify global + * rules or device rules for the given `profile_tag`. + */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + }; + responses: { + /** The actions for this push rule. */ + 200: { + schema: { + /** @description The action(s) to perform for this rule. */ + actions: unknown[]; + }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This endpoint allows clients to change the actions of a push rule. + * This can be used to change the actions of builtin rules. + */ + setPushRuleActions: { + parameters: { + path: { + /** `global` to specify global rules. */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + body: { + /** The action(s) to perform when the conditions for this rule are met. */ + body: { + /** @description The action(s) to perform for this rule. */ + actions: unknown[]; + }; + }; + }; + responses: { + /** The actions for the push rule were set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** This endpoint gets whether the specified push rule is enabled. */ + isPushRuleEnabled: { + parameters: { + path: { + /** + * Either `global` or `device/` to specify global + * rules or device rules for the given `profile_tag`. + */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + }; + responses: { + /** Whether the push rule is enabled. */ + 200: { + schema: { + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** This endpoint allows clients to enable or disable the specified push rule. */ + setPushRuleEnabled: { + parameters: { + path: { + /** `global` to specify global rules. */ + scope: string; + /** The kind of rule */ + kind: "override" | "underride" | "sender" | "room" | "content"; + /** The identifier for the rule. */ + ruleId: string; + }; + body: { + /** Whether the push rule is enabled or not. */ + body: { + /** @description Whether the push rule is enabled or not. */ + enabled: boolean; + }; + }; + }; + responses: { + /** The push rule was enabled or disabled. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The push rule does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Refresh an access token. Clients should use the returned access token + * when making subsequent API calls, and store the returned refresh token + * (if given) in order to refresh the new access token when necessary. + * + * After an access token has been refreshed, a server can choose to + * invalidate the old access token immediately, or can choose not to, for + * example if the access token would expire soon anyways. Clients should + * not make any assumptions about the old access token still being valid, + * and should use the newly provided access token instead. + * + * The old refresh token remains valid until the new access token or refresh token + * is used, at which point the old refresh token is revoked. + * + * Note that this endpoint does not require authentication via an + * access token. Authentication is provided via the refresh token. + * + * Application Service identity assertion is disabled for this endpoint. + */ + refresh: { + parameters: { + body: { + body: { + /** @description The refresh token */ + refresh_token: string; + }; + }; + }; + responses: { + /** A new access token and refresh token were generated. */ + 200: { + schema: { + /** @description The new access token to use. */ + access_token: string; + /** + * @description The lifetime of the access token, in milliseconds. If not + * given, the client can assume that the access token will not + * expire. + */ + expires_in_ms?: number; + /** + * @description The new refresh token to use when the access token needs to + * be refreshed again. If not given, the old refresh token can + * be re-used. + */ + refresh_token?: string; + }; + }; + /** The provided token was unknown, or has already been used. */ + 401: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This API endpoint uses the [User-Interactive Authentication API](https://spec.matrix.org/v1.7/client-server-api/#user-interactive-authentication-api), except in + * the cases where a guest account is being registered. + * + * Register for an account on this homeserver. + * + * There are two kinds of user account: + * + * - `user` accounts. These accounts may use the full API described in this specification. + * + * - `guest` accounts. These accounts may have limited permissions and may not be supported by all servers. + * + * If registration is successful, this endpoint will issue an access token + * the client can use to authorize itself in subsequent requests. + * + * If the client does not supply a `device_id`, the server must + * auto-generate one. + * + * The server SHOULD register an account with a User ID based on the + * `username` provided, if any. Note that the grammar of Matrix User ID + * localparts is restricted, so the server MUST either map the provided + * `username` onto a `user_id` in a logical manner, or reject any + * `username` which does not comply to the grammar with + * `M_INVALID_USERNAME`. + * + * Matrix clients MUST NOT assume that localpart of the registered + * `user_id` matches the provided `username`. + * + * The returned access token must be associated with the `device_id` + * supplied by the client or generated by the server. The server may + * invalidate any access token previously associated with that device. See + * [Relationship between access tokens and devices](https://spec.matrix.org/v1.7/client-server-api/#relationship-between-access-tokens-and-devices). + * + * When registering a guest account, all parameters in the request body + * with the exception of `initial_device_display_name` MUST BE ignored + * by the server. The server MUST pick a `device_id` for the account + * regardless of input. + * + * Any user ID returned by this API must conform to the grammar given in the + * [Matrix specification](https://spec.matrix.org/v1.7/appendices/#user-identifiers). + */ + register: { + parameters: { + query: { + /** The kind of account to register. Defaults to `user`. */ + kind?: "guest" | "user"; + }; + body: { + body: { + /** + * @description Additional authentication information for the + * user-interactive authentication API. Note that this + * information is *not* used to define how the registered user + * should be authenticated, but is instead used to + * authenticate the `register` call itself. + */ + auth?: { + /** @description The value of the session key given by the homeserver. */ + session?: string; + /** + * @description The authentication type that the client is attempting to complete. + * May be omitted if `session` is given, and the client is reissuing a + * request which it believes has been completed out-of-band (for example, + * via the [fallback mechanism](#fallback)). + */ + type?: string; + } & { [key: string]: unknown }; + /** + * @description ID of the client device. If this does not correspond to a + * known client device, a new device will be created. The server + * will auto-generate a device_id if this is not specified. + * @example GHTYAJCE + */ + device_id?: string; + /** + * @description If true, an `access_token` and `device_id` should not be + * returned from this call, therefore preventing an automatic + * login. Defaults to false. + * @example false + */ + inhibit_login?: boolean; + /** + * @description A display name to assign to the newly-created device. Ignored + * if `device_id` corresponds to a known device. + * @example Jungle Phone + */ + initial_device_display_name?: string; + /** + * @description The desired password for the account. + * @example ilovebananas + */ + password?: string; + /** @description If true, the client supports refresh tokens. */ + refresh_token?: boolean; + /** + * @description The basis for the localpart of the desired Matrix ID. If omitted, + * the homeserver MUST generate a Matrix ID local part. + * @example cheeky_monkey + */ + username?: string; + }; + }; + }; + responses: { + /** The account has been registered. */ + 200: { + schema: { + /** + * @description An access token for the account. + * This access token can then be used to authorize other requests. + * Required if the `inhibit_login` option is false. + */ + access_token?: string; + /** + * @description ID of the registered device. Will be the same as the + * corresponding parameter in the request, if one was specified. + * Required if the `inhibit_login` option is false. + */ + device_id?: string; + /** + * @description The lifetime of the access token, in milliseconds. Once + * the access token has expired a new access token can be + * obtained by using the provided refresh token. If no + * refresh token is provided, the client will need to re-log in + * to obtain a new access token. If not given, the client can + * assume that the access token will not expire. + * + * Omitted if the `inhibit_login` option is true. + */ + expires_in_ms?: number; + /** + * @description The server_name of the homeserver on which the account has + * been registered. + * + * **Deprecated**. Clients should extract the server_name from + * `user_id` (by splitting at the first colon) if they require + * it. Note also that `homeserver` is not spelt this way. + */ + home_server?: string; + /** + * @description A refresh token for the account. This token can be used to + * obtain a new access token when it expires by calling the + * `/refresh` endpoint. + * + * Omitted if the `inhibit_login` option is true. + */ + refresh_token?: string; + /** + * @description The fully-qualified Matrix user ID (MXID) that has been registered. + * + * Any user ID returned by this API must conform to the grammar given in the + * [Matrix specification](https://spec.matrix.org/v1.7/appendices/#user-identifiers). + */ + user_id: string; + }; + }; + /** + * Part of the request was invalid. This may include one of the following error codes: + * + * * `M_USER_IN_USE` : The desired user ID is already taken. + * * `M_INVALID_USERNAME` : The desired user ID is not a valid user name. + * * `M_EXCLUSIVE` : The desired user ID is in the exclusive namespace + * claimed by an application service. + * + * These errors may be returned at any stage of the registration process, + * including after authentication if the requested user ID was registered + * whilst the client was performing authentication. + * + * Homeservers MUST perform the relevant checks and return these codes before + * performing User-Interactive Authentication, although they may also return + * them after authentication is completed if, for example, the requested user ID + * was registered whilst the client was performing authentication. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The homeserver requires additional authentication information. */ + 401: { + schema: { + /** @description A list of the stages the client has completed successfully */ + completed?: string[]; + /** @description A list of the login flows supported by the server for this API. */ + flows: { + /** + * @description The login type of each of the stages required to complete this + * authentication flow + */ + stages: string[]; + }[]; + /** + * @description Contains any information that the client will need to know in order to + * use a given type of authentication. For each login type presented, + * that type may be present as a key in this dictionary. For example, the + * public part of an OAuth client ID could be given here. + * @example { + * "example.type.baz": { + * "example_key": "foobar" + * } + * } + */ + params?: { [key: string]: { [key: string]: unknown } }; + /** + * @description This is a session identifier that the client must pass back to the home + * server, if one is provided, in subsequent attempts to authenticate in the + * same API call. + * @example xxxxxxyz + */ + session?: string; + }; + }; + /** + * The homeserver does not permit registering the account. This response + * can be used to identify that a particular `kind` of account is not + * allowed, or that registration is generally not supported by the homeserver. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Checks to see if a username is available, and valid, for the server. + * + * The server should check to ensure that, at the time of the request, the + * username requested is available for use. This includes verifying that an + * application service has not claimed the username and that the username + * fits the server's desired requirements (for example, a server could dictate + * that it does not permit usernames with underscores). + * + * Matrix clients may wish to use this API prior to attempting registration, + * however the clients must also be aware that using this API does not normally + * reserve the username. This can mean that the username becomes unavailable + * between checking its availability and attempting to register it. + */ + checkUsernameAvailability: { + parameters: { + query: { + /** The username to check the availability of. */ + username: string; + }; + }; + responses: { + /** The username is available */ + 200: { + schema: { + /** + * @description A flag to indicate that the username is available. This should always + * be `true` when the server replies with 200 OK. + */ + available?: boolean; + }; + }; + /** + * Part of the request was invalid or the username is not available. This may + * include one of the following error codes: + * + * * `M_USER_IN_USE` : The desired username is already taken. + * * `M_INVALID_USERNAME` : The desired username is not a valid user name. + * * `M_EXCLUSIVE` : The desired username is in the exclusive namespace + * claimed by an application service. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * The homeserver must check that the given email address is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the email itself, either by sending a validation email + * itself or by using a service it has control over. + */ + requestTokenToRegisterEmail: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The email address to validate. + * @example alice@example.org + */ + email: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The server will only send an email if the `send_attempt` + * is a number greater than the most recent one which it has seen, + * scoped to that `email` + `client_secret` pair. This is to + * avoid repeatedly sending the same email in the case of request + * retries between the POSTing user and the identity server. + * The client should increment this value if they desire a new + * email (e.g. a reminder) to be sent. If they do not, the server + * should respond with success but not resend the email. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** + * An email has been sent to the specified address. Note that this + * may be an email containing the validation token or it may be + * informing the user of an error. + */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * Part of the request was invalid. This may include one of the following error codes: + * + * * `M_THREEPID_IN_USE` : The email address is already registered to an account on this server. + * However, if the homeserver has the ability to send email, it is recommended that the server + * instead send an email to the user with instructions on how to reset their password. + * This prevents malicious parties from being able to determine if a given email address + * has an account on the homeserver in question. + * * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server + * that is not trusted by this homeserver. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The homeserver does not permit the address to be bound. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * The homeserver must check that the given phone number is **not** + * already associated with an account on this homeserver. The homeserver + * should validate the phone number itself, either by sending a validation + * message itself or by using a service it has control over. + */ + requestTokenToRegisterMSISDN: { + parameters: { + body: { + body: { + /** + * @description A unique string generated by the client, and used to identify the + * validation attempt. It must be a string consisting of the characters + * `[0-9a-zA-Z.=_-]`. Its length must not exceed 255 characters and it + * must not be empty. + * + * @example monkeys_are_GREAT + */ + client_secret: string; + /** + * @description The two-letter uppercase ISO-3166-1 alpha-2 country code that the + * number in `phone_number` should be parsed as if it were dialled from. + * @example GB + */ + country: string; + /** + * @description Optional. When the validation is completed, the identity server will + * redirect the user to this URL. This option is ignored when submitting + * 3PID validation information through a POST request. + * @example https://example.org/congratulations.html + */ + next_link?: string; + /** + * @description The phone number to validate. + * @example 07700900001 + */ + phone_number: string; + /** + * @description The server will only send an SMS if the `send_attempt` is a + * number greater than the most recent one which it has seen, + * scoped to that `country` + `phone_number` + `client_secret` + * triple. This is to avoid repeatedly sending the same SMS in + * the case of request retries between the POSTing user and the + * identity server. The client should increment this value if + * they desire a new SMS (e.g. a reminder) to be sent. + * @example 1 + */ + send_attempt: number; + } & { + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + * + * Required if an `id_server` is supplied. + */ + id_access_token?: string; + /** + * @description The hostname of the identity server to communicate with. May optionally + * include a port. This parameter is ignored when the homeserver handles + * 3PID verification. + * + * This parameter is deprecated with a plan to be removed in a future specification + * version for `/account/password` and `/register` requests. + * @example id.example.com + */ + id_server?: string; + }; + }; + }; + responses: { + /** + * An SMS message has been sent to the specified phone number. Note + * that this may be an SMS message containing the validation token or + * it may be informing the user of an error. + */ + 200: { + schema: { + /** + * @description The session ID. Session IDs are opaque strings that must consist entirely + * of the characters `[0-9a-zA-Z.=_-]`. Their length must not exceed 255 + * characters and they must not be empty. + * @example 123abc + */ + sid: string; + /** + * Format: uri + * @description An optional field containing a URL where the client must submit the + * validation token to, with identical parameters to the Identity Service + * API's `POST /validate/email/submitToken` endpoint (without the requirement + * for an access token). The homeserver must send this token to the user (if + * applicable), who should then be prompted to provide it to the client. + * + * If this field is not present, the client can assume that verification + * will happen without the client's involvement provided the homeserver + * advertises this specification version in the `/versions` response + * (ie: r0.5.0). + * @example https://example.org/path/to/submitToken + */ + submit_url?: string; + }; + }; + /** + * Part of the request was invalid. This may include one of the following error codes: + * + * * `M_THREEPID_IN_USE` : The phone number is already registered to an account on this server. + * However, if the homeserver has the ability to send SMS message, it is recommended that the server + * instead send an SMS message to the user with instructions on how to reset their password. + * This prevents malicious parties from being able to determine if a given phone number + * has an account on the homeserver in question. + * * `M_SERVER_NOT_TRUSTED` : The `id_server` parameter refers to an identity server + * that is not trusted by this homeserver. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The homeserver does not permit the address to be bound. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** Retrieve the keys from the backup. */ + getRoomKeys: { + parameters: { + query: { + /** The backup from which to retrieve the keys. */ + version: string; + }; + }; + responses: { + /** + * The key data. If no keys are found, then an object with an empty + * `rooms` property will be returned (`{"rooms": {}}`). + */ + 200: { + schema: { + /** + * @description A map of room IDs to room key backup data. + * @example { + * "!room:example.org": { + * "sessions": { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + * } + * } + */ + rooms: { + [key: string]: { + /** + * @description A map of session IDs to key data. + * @example { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + */ + sessions: { + [key: string]: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + }; + }; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Store several keys in the backup. */ + putRoomKeys: { + parameters: { + query: { + /** The backup in which to store the keys. Must be the current backup. */ + version: string; + }; + body: { + /** The backup data. */ + backupData: { + /** + * @description A map of room IDs to room key backup data. + * @example { + * "!room:example.org": { + * "sessions": { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + * } + * } + */ + rooms: { + [key: string]: { + /** + * @description A map of session IDs to key data. + * @example { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + */ + sessions: { + [key: string]: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + }; + }; + }; + }; + }; + responses: { + /** The update succeeded */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** + * The version specified does not match the current backup version. + * The current version will be included in the `current_version` + * field. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Delete the keys from the backup. */ + deleteRoomKeys: { + parameters: { + query: { + /** The backup from which to delete the key */ + version: string; + }; + }; + responses: { + /** The update succeeded */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Retrieve the keys from the backup for a given room. */ + getRoomKeysByRoomId: { + parameters: { + query: { + /** The backup from which to retrieve the key. */ + version: string; + }; + path: { + /** The ID of the room that the requested key is for. */ + roomId: string; + }; + }; + responses: { + /** + * The key data. If no keys are found, then an object with an empty + * `sessions` property will be returned (`{"sessions": {}}`). + */ + 200: { + schema: { + /** + * @description A map of session IDs to key data. + * @example { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + */ + sessions: { + [key: string]: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Store several keys in the backup for a given room. */ + putRoomKeysByRoomId: { + parameters: { + query: { + /** The backup in which to store the keys. Must be the current backup. */ + version: string; + }; + path: { + /** The ID of the room that the keys are for. */ + roomId: string; + }; + body: { + /** The backup data */ + backupData: { + /** + * @description A map of session IDs to key data. + * @example { + * "sessionid1": { + * "first_message_index": 1, + * "forwarded_count": 0, + * "is_verified": true, + * "session_data": { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + * } + * } + */ + sessions: { + [key: string]: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + }; + }; + }; + responses: { + /** The update succeeded */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** + * The version specified does not match the current backup version. + * The current version will be included in the `current_version` + * field. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Delete the keys from the backup for a given room. */ + deleteRoomKeysByRoomId: { + parameters: { + query: { + /** The backup from which to delete the key. */ + version: string; + }; + path: { + /** The ID of the room that the specified key is for. */ + roomId: string; + }; + }; + responses: { + /** The update succeeded */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Retrieve a key from the backup. */ + getRoomKeyBySessionId: { + parameters: { + query: { + /** The backup from which to retrieve the key. */ + version: string; + }; + path: { + /** The ID of the room that the requested key is for. */ + roomId: string; + /** The ID of the megolm session whose key is requested. */ + sessionId: string; + }; + }; + responses: { + /** The key data */ + 200: { + schema: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + /** The key or backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Store a key in the backup. */ + putRoomKeyBySessionId: { + parameters: { + query: { + /** The backup in which to store the key. Must be the current backup. */ + version: string; + }; + path: { + /** The ID of the room that the key is for. */ + roomId: string; + /** The ID of the megolm session that the key is for. */ + sessionId: string; + }; + body: { + /** The key data. */ + data: { + /** + * @description The index of the first message in the session that the key can decrypt. + * @example 1 + */ + first_message_index: number; + /** + * @description The number of times this key has been forwarded via key-sharing between devices. + * @example 0 + */ + forwarded_count: number; + /** + * @description Whether the device backing up the key verified the device that the key + * is from. + * @example false + */ + is_verified: boolean; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "ciphertext": "base64+ciphertext+of+JSON+data", + * "ephemeral": "base64+ephemeral+key", + * "mac": "base64+mac+of+ciphertext" + * } + */ + session_data: { [key: string]: unknown }; + }; + }; + }; + responses: { + /** The update succeeded. */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** + * The version specified does not match the current backup version. + * The current version will be included in the `current_version` + * field. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Delete a key from the backup. */ + deleteRoomKeyBySessionId: { + parameters: { + query: { + /** The backup from which to delete the key */ + version: string; + }; + path: { + /** The ID of the room that the specified key is for. */ + roomId: string; + /** The ID of the megolm session whose key is to be deleted. */ + sessionId: string; + }; + }; + responses: { + /** The update succeeded */ + 200: { + schema: { + /** + * @description The number of keys stored in the backup + * @example 10 + */ + count: number; + /** + * @description The new etag value representing stored keys in the backup. + * See `GET /room_keys/version/{version}` for more details. + * @example abcdefg + */ + etag: string; + }; + }; + /** The backup was not found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Get information about the latest backup version. */ + getRoomKeysVersionCurrent: { + responses: { + /** The information about the backup. */ + 200: { + schema: { + /** + * @description The algorithm used for storing backups. + * @example m.megolm_backup.v1.curve25519-aes-sha2 + * @enum {string} + */ + algorithm: "m.megolm_backup.v1.curve25519-aes-sha2"; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "public_key": "abcdefg", + * "signatures": { + * "@alice:example.org": { + * "ed25519:deviceid": "signature" + * } + * } + * } + */ + auth_data: { [key: string]: unknown }; + /** + * @description The number of keys stored in the backup. + * @example 42 + */ + count: number; + /** + * @description An opaque string representing stored keys in the backup. + * Clients can compare it with the `etag` value they received + * in the request of their last key storage request. If not + * equal, another client has modified the backup. + * @example anopaquestring + */ + etag: string; + /** + * @description The backup version. + * @example 1 + */ + version: string; + }; + }; + /** No backup exists. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Creates a new backup. */ + postRoomKeysVersion: { + parameters: { + body: { + /** The backup configuration. */ + version: { + /** + * @description The algorithm used for storing backups. + * @example m.megolm_backup.v1.curve25519-aes-sha2 + * @enum {string} + */ + algorithm: "m.megolm_backup.v1.curve25519-aes-sha2"; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "public_key": "abcdefg", + * "signatures": { + * "@alice:example.org": { + * "ed25519:deviceid": "signature" + * } + * } + * } + */ + auth_data: { [key: string]: unknown }; + }; + }; + }; + responses: { + /** The version id of the new backup. */ + 200: { + schema: { + /** + * @description The backup version. This is an opaque string. + * @example 1 + */ + version: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Get information about an existing backup. */ + getRoomKeysVersion: { + parameters: { + path: { + /** + * The backup version to get, as returned in the `version` parameter + * of the response in + * [`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3room_keysversion) + * or this endpoint. + */ + version: string; + }; + }; + responses: { + /** The information about the requested backup. */ + 200: { + schema: { + /** + * @description The algorithm used for storing backups. + * @example m.megolm_backup.v1.curve25519-aes-sha2 + * @enum {string} + */ + algorithm: "m.megolm_backup.v1.curve25519-aes-sha2"; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "public_key": "abcdefg", + * "signatures": { + * "@alice:example.org": { + * "ed25519:deviceid": "signature" + * } + * } + * } + */ + auth_data: { [key: string]: unknown }; + /** + * @description The number of keys stored in the backup. + * @example 42 + */ + count: number; + /** + * @description An opaque string representing stored keys in the backup. + * Clients can compare it with the `etag` value they received + * in the request of their last key storage request. If not + * equal, another client has modified the backup. + * @example anopaquestring + */ + etag: string; + /** + * @description The backup version. + * @example 1 + */ + version: string; + }; + }; + /** The backup specified does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Update information about an existing backup. Only `auth_data` can be modified. */ + putRoomKeysVersion: { + parameters: { + path: { + /** + * The backup version to update, as returned in the `version` + * parameter in the response of + * [`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3room_keysversion) + * or [`GET /_matrix/client/v3/room_keys/version/{version}`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3room_keysversionversion). + */ + version: string; + }; + body: { + /** The backup configuration */ + version: { + /** + * @description The algorithm used for storing backups. Must be the same as + * the algorithm currently used by the backup. + * @example m.megolm_backup.v1.curve25519-aes-sha2 + * @enum {string} + */ + algorithm: "m.megolm_backup.v1.curve25519-aes-sha2"; + /** + * @description Algorithm-dependent data. See the documentation for the backup + * algorithms in [Server-side key backups](https://spec.matrix.org/v1.7/client-server-api/#server-side-key-backups) for more information on the + * expected format of the data. + * @example { + * "public_key": "abcdefg", + * "signatures": { + * "@alice:example.org": { + * "ed25519:deviceid": "signature" + * } + * } + * } + */ + auth_data: { [key: string]: unknown }; + /** + * @description The backup version. If present, must be the same as the + * version in the path parameter. + * @example 1 + */ + version?: string; + }; + }; + }; + responses: { + /** The update succeeded. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * A parameter was incorrect. For example, the `algorithm` does not + * match the current backup algorithm, or the `version` in the body + * does not match the `version` in the path. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The backup specified does not exist. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Delete an existing key backup. Both the information about the backup, + * as well as all key data related to the backup will be deleted. + */ + deleteRoomKeysVersion: { + parameters: { + path: { + /** + * The backup version to delete, as returned in the `version` + * parameter in the response of + * [`POST /_matrix/client/v3/room_keys/version`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3room_keysversion) + * or [`GET /_matrix/client/v3/room_keys/version/{version}`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3room_keysversionversion). + */ + version: string; + }; + }; + responses: { + /** + * The delete succeeded, or the specified backup was previously + * deleted. + */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The backup specified does not exist. If the backup was previously + * deleted, the call should succeed rather than returning an error. + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get a list of aliases maintained by the local server for the + * given room. + * + * This endpoint can be called by users who are in the room (external + * users receive an `M_FORBIDDEN` error response). If the room's + * `m.room.history_visibility` maps to `world_readable`, any + * user can call this endpoint. + * + * Servers may choose to implement additional access control checks here, + * such as allowing server administrators to view aliases regardless of + * membership. + * + * **Note:** + * Clients are recommended not to display this list of aliases prominently + * as they are not curated, unlike those listed in the `m.room.canonical_alias` + * state event. + */ + getLocalAliases: { + parameters: { + path: { + /** The room ID to find local aliases of. */ + roomId: string; + }; + }; + responses: { + /** The list of local aliases for the room. */ + 200: { + schema: { + /** @description The server's local aliases on the room. Can be empty. */ + aliases: string[]; + }; + }; + /** The given `roomAlias` is not a valid room alias. */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The user is not permitted to retrieve the list of local aliases for the room. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Ban a user in the room. If the user is currently in the room, also kick them. + * + * When a user is banned from a room, they may not join it or be invited to it until they are unbanned. + * + * The caller must have the required power level in order to perform this operation. + */ + ban: { + parameters: { + path: { + /** The room identifier (not alias) from which the user should be banned. */ + roomId: string; + }; + body: { + body: { + /** @description The reason the user has been banned. This will be supplied as the `reason` on the target's updated [`m.room.member`](https://spec.matrix.org/v1.7/client-server-api/#mroommember) event. */ + reason?: string; + /** @description The fully qualified user ID of the user being banned. */ + user_id: string; + }; + }; + }; + responses: { + /** The user has been kicked and banned from the room. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + * + * - The banner is not currently in the room. + * - The banner's power level is insufficient to ban users from the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API returns a number of events that happened just before and + * after the specified event. This allows clients to get the context + * surrounding an event. + * + * *Note*: This endpoint supports lazy-loading of room member events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) for more information. + */ + getEventContext: { + parameters: { + path: { + /** The room to get events from. */ + roomId: string; + /** The event to get context around. */ + eventId: string; + }; + query: { + /** + * The maximum number of context events to return. The limit applies + * to the sum of the `events_before` and `events_after` arrays. The + * requested event ID is always returned in `event` even if `limit` is + * 0. Defaults to 10. + */ + limit?: number; + /** + * A JSON `RoomEventFilter` to filter the returned events with. The + * filter is only applied to `events_before`, `events_after`, and + * `state`. It is not applied to the `event` itself. The filter may + * be applied before or/and after the `limit` parameter - whichever the + * homeserver prefers. + * + * See [Filtering](https://spec.matrix.org/v1.7/client-server-api/#filtering) for more information. + */ + filter?: string; + }; + }; + responses: { + /** The events and state surrounding the requested event. */ + 200: { + schema: { + /** @description A token that can be used to paginate forwards with. */ + end?: string; + /** @description Details of the requested event. */ + event?: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + }; + /** + * @description A list of room events that happened just after the + * requested event, in chronological order. + */ + events_after?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A list of room events that happened just before the + * requested event, in reverse-chronological order. + */ + events_before?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** @description A token that can be used to paginate backwards with. */ + start?: string; + /** @description The state of the room at the last event returned. */ + state?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + }; + }; + }; + }; + /** + * Get a single event based on `roomId/eventId`. You must have permission to + * retrieve this event e.g. by being a member in the room for this event. + */ + getOneRoomEvent: { + parameters: { + path: { + /** The ID of the room the event is in. */ + roomId: string; + /** The event ID to get. */ + eventId: string; + }; + }; + responses: { + /** The full event. */ + 200: { + schema: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + }; + }; + /** The event was not found or you do not have permission to read this event. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API stops a user remembering about a particular room. + * + * In general, history is a first class citizen in Matrix. After this API + * is called, however, a user will no longer be able to retrieve history + * for this room. If all users on a homeserver forget a room, the room is + * eligible for deletion from that homeserver. + * + * If the user is currently joined to the room, they must leave the room + * before calling this API. + */ + forgetRoom: { + parameters: { + path: { + /** The room identifier to forget. */ + roomId: string; + }; + }; + responses: { + /** The room has been forgotten. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The user has not left the room */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get a copy of the current state and the most recent messages in a room. + * + * This endpoint was deprecated in r0 of this specification. There is no + * direct replacement; the relevant information is returned by the + * [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) API. See the + * [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints). + */ + roomInitialSync: { + parameters: { + path: { + /** The room to get the data. */ + roomId: string; + }; + }; + responses: { + /** The current state of the room */ + 200: { + schema: { + /** @description The private data that this user has attached to this room. */ + account_data?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + /** + * @description The user's membership state in this room. + * @enum {string} + */ + membership?: "invite" | "join" | "leave" | "ban"; + /** + * PaginationChunk + * @description The pagination chunk for this room. + */ + messages?: { + /** + * @description If the user is a member of the room this will be a + * list of the most recent messages for this room. If + * the user has left the room this will be the + * messages that preceded them leaving. This array + * will consist of at most `limit` elements. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token which correlates to the end of `chunk`. Can be passed to + * [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + * to retrieve later events. + */ + end: string; + /** + * @description A token which correlates to the start of `chunk`. Can be passed to + * [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) + * to retrieve earlier events. + * + * If no earlier events are available, this property may be omitted from + * the response. + */ + start?: string; + }; + /** @description The ID of this room. */ + room_id: string; + /** + * @description If the user is a member of the room this will be the + * current state of the room as a list of events. If the + * user has left the room this will be the state of the + * room when they left it. + */ + state?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description Whether this room is visible to the `/publicRooms` API + * or not." + * @enum {string} + */ + visibility?: "private" | "public"; + }; + }; + /** You aren't a member of the room and weren't previously a member of the room. */ + 403: unknown; + }; + }; + /** + * *Note that there are two forms of this API, which are documented separately. + * This version of the API does not require that the inviter know the Matrix + * identifier of the invitee, and instead relies on third-party identifiers. + * The homeserver uses an identity server to perform the mapping from + * third-party identifier to a Matrix identifier. The other is documented in the* + * [joining rooms section](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3roomsroomidinvite). + * + * This API invites a user to participate in a particular room. + * They do not start participating in the room until they actually join the + * room. + * + * Only users currently in a particular room can invite other users to + * join that room. + * + * If the identity server did know the Matrix user identifier for the + * third-party identifier, the homeserver will append a `m.room.member` + * event to the room. + * + * If the identity server does not know a Matrix user identifier for the + * passed third-party identifier, the homeserver will issue an invitation + * which can be accepted upon providing proof of ownership of the third- + * party identifier. This is achieved by the identity server generating a + * token, which it gives to the inviting homeserver. The homeserver will + * add an `m.room.third_party_invite` event into the graph for the room, + * containing that token. + * + * When the invitee binds the invited third-party identifier to a Matrix + * user ID, the identity server will give the user a list of pending + * invitations, each containing: + * + * - The room ID to which they were invited + * + * - The token given to the homeserver + * + * - A signature of the token, signed with the identity server's private key + * + * - The matrix user ID who invited them to the room + * + * If a token is requested from the identity server, the homeserver will + * append a `m.room.third_party_invite` event to the room. + */ + inviteBy3PID: { + parameters: { + path: { + /** The room identifier (not alias) to which to invite the user. */ + roomId: string; + }; + body: { + body: { + /** @description The invitee's third-party identifier. */ + address: string; + /** + * @description An access token previously registered with the identity server. Servers + * can treat this as optional to distinguish between r0.5-compatible clients + * and this specification version. + */ + id_access_token: string; + /** @description The hostname+port of the identity server which should be used for third-party identifier lookups. */ + id_server: string; + /** + * @description The kind of address being passed in the address field, for example + * `email` (see [the list of recognised values](https://spec.matrix.org/v1.7/appendices/#3pid-types)). + */ + medium: string; + }; + }; + }; + responses: { + /** The user has been invited to join the room. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + * + * - The invitee has been banned from the room. + * - The invitee is already a member of the room. + * - The inviter is not currently in the room. + * - The inviter's power level is insufficient to invite users to the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * *Note that there are two forms of this API, which are documented separately. + * This version of the API requires that the inviter knows the Matrix + * identifier of the invitee. The other is documented in the + * [third-party invites](https://spec.matrix.org/v1.7/client-server-api/#third-party-invites) section.* + * + * This API invites a user to participate in a particular room. + * They do not start participating in the room until they actually join the + * room. + * + * Only users currently in a particular room can invite other users to + * join that room. + * + * If the user was invited to the room, the homeserver will append a + * `m.room.member` event to the room. + */ + inviteUser: { + parameters: { + path: { + /** The room identifier (not alias) to which to invite the user. */ + roomId: string; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + */ + reason?: string; + /** @description The fully qualified user ID of the invitee. */ + user_id: string; + }; + }; + }; + responses: { + /** The user has been invited to join the room, or was already invited to the room. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The request is invalid. A meaningful `errcode` and description + * error text will be returned. Example reasons for rejection include: + * + * - The request body is malformed (`errcode` set to `M_BAD_JSON` + * or `M_NOT_JSON`). + * + * - One or more users being invited to the room are residents of a + * homeserver which does not support the requested room version. The + * `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * You do not have permission to invite the user to the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + * + * - The invitee has been banned from the room. + * - The invitee is already a member of the room. + * - The inviter is not currently in the room. + * - The inviter's power level is insufficient to invite users to the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * *Note that this API requires a room ID, not alias.* + * `/join/{roomIdOrAlias}` *exists if you have a room alias.* + * + * This API starts a user participating in a particular room, if that user + * is allowed to participate in that room. After this call, the client is + * allowed to see all current state events in the room, and all subsequent + * events associated with the room until the user leaves the room. + * + * After a user has joined a room, the room will appear as an entry in the + * response of the [`/initialSync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3initialsync) + * and [`/sync`](https://spec.matrix.org/v1.7/client-server-api/#get_matrixclientv3sync) APIs. + */ + joinRoomById: { + parameters: { + path: { + /** The room identifier (not alias) to join. */ + roomId: string; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + * @example Looking for support + */ + reason?: string; + /** + * @description If supplied, the homeserver must verify that it matches a pending + * `m.room.third_party_invite` event in the room, and perform + * key validity checking if required by the event. + */ + third_party_signed?: { + /** + * @description The Matrix ID of the invitee. + * @example @bob:example.org + */ + mxid: string; + /** + * @description The Matrix ID of the user who issued the invite. + * @example @alice:example.org + */ + sender: string; + /** + * Signatures + * @description A signatures object containing a signature of the entire signed object. + * @example { + * "example.org": { + * "ed25519:0": "some9signature" + * } + * } + */ + signatures: { [key: string]: { [key: string]: string } }; + /** + * @description The state key of the m.third_party_invite event. + * @example random8nonce + */ + token: string; + }; + }; + }; + }; + responses: { + /** + * The room has been joined. + * + * The joined room ID must be returned in the `room_id` field. + */ + 200: { + schema: { + /** @description The joined room ID. */ + room_id: string; + }; + }; + /** + * You do not have permission to join the room. A meaningful `errcode` + * and description error text will be returned. Example reasons for rejection are: + * + * - The room is invite-only and the user was not invited. + * - The user has been banned from the room. + * - The room is restricted and the user failed to satisfy any of the conditions. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than `/members` as it can be implemented more efficiently on the server. */ + getJoinedMembersByRoom: { + parameters: { + path: { + /** The room to get the members of. */ + roomId: string; + }; + }; + responses: { + /** A map of MXID to room member objects. */ + 200: { + schema: { + /** @description A map from user ID to a RoomMember object. */ + joined?: { + [key: string]: { + /** + * Format: uri + * @description The avatar of the user this object is representing, as an [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris). + */ + avatar_url?: string; + /** @description The display name of the user this object is representing. */ + display_name?: string; + }; + }; + }; + }; + /** You aren't a member of the room. */ + 403: unknown; + }; + }; + /** + * Kick a user from the room. + * + * The caller must have the required power level in order to perform this operation. + * + * Kicking a user adjusts the target member's membership state to be `leave` with an + * optional `reason`. Like with other membership changes, a user can directly adjust + * the target member's state by making a request to `/rooms//state/m.room.member/`. + */ + kick: { + parameters: { + path: { + /** The room identifier (not alias) from which the user should be kicked. */ + roomId: string; + }; + body: { + body: { + /** + * @description The reason the user has been kicked. This will be supplied as the + * `reason` on the target's updated [`m.room.member`](https://spec.matrix.org/v1.7/client-server-api/#mroommember) event. + */ + reason?: string; + /** @description The fully qualified user ID of the user being kicked. */ + user_id: string; + }; + }; + }; + responses: { + /** The user has been kicked from the room. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * You do not have permission to kick the user from the room. A meaningful `errcode` and + * description error text will be returned. Example reasons for rejections are: + * + * - The kicker is not currently in the room. + * - The kickee is not currently in the room. + * - The kicker's power level is insufficient to kick users from the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This API stops a user participating in a particular room. + * + * If the user was already in the room, they will no longer be able to see + * new events in the room. If the room requires an invite to join, they + * will need to be re-invited before they can re-join. + * + * If the user was invited to the room, but had not joined, this call + * serves to reject the invite. + * + * The user will still be allowed to retrieve history from the room which + * they were previously allowed to see. + */ + leaveRoom: { + parameters: { + path: { + /** The room identifier to leave. */ + roomId: string; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + */ + reason?: string; + }; + }; + }; + responses: { + /** The room has been left. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** Get the list of members for this room. */ + getMembersByRoom: { + parameters: { + path: { + /** The room to get the member events for. */ + roomId: string; + }; + query: { + /** + * The point in time (pagination token) to return members for in the room. + * This token can be obtained from a `prev_batch` token returned for + * each room by the sync API. Defaults to the current state of the room, + * as determined by the server. + */ + at?: string; + /** + * The kind of membership to filter for. Defaults to no filtering if + * unspecified. When specified alongside `not_membership`, the two + * parameters create an 'or' condition: either the membership *is* + * the same as `membership` **or** *is not* the same as `not_membership`. + */ + membership?: "join" | "invite" | "knock" | "leave" | "ban"; + /** + * The kind of membership to exclude from the results. Defaults to no + * filtering if unspecified. + */ + not_membership?: "join" | "invite" | "knock" | "leave" | "ban"; + }; + }; + responses: { + /** + * A list of members of the room. If you are joined to the room then + * this will be the current members of the room. If you have left the + * room then this will be the members of the room when you left. + */ + 200: { + schema: { + chunk?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + }; + }; + /** You aren't a member of the room and weren't previously a member of the room. */ + 403: unknown; + }; + }; + /** + * This API returns a list of message and state events for a room. It uses + * pagination query parameters to paginate history in the room. + * + * *Note*: This endpoint supports lazy-loading of room member events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) for more information. + */ + getRoomEvents: { + parameters: { + path: { + /** The room to get events from. */ + roomId: string; + }; + query: { + /** + * The token to start returning events from. This token can be obtained + * from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint, + * or from an `end` token returned by a previous request to this endpoint. + * + * This endpoint can also accept a value returned as a `start` token + * by a previous request to this endpoint, though servers are not + * required to support this. Clients should not rely on the behaviour. + * + * If it is not provided, the homeserver shall return a list of messages + * from the first or last (per the value of the `dir` parameter) visible + * event in the room history for the requesting user. + */ + from?: string; + /** + * The token to stop returning events at. This token can be obtained from + * a `prev_batch` or `next_batch` token returned by the `/sync` endpoint, + * or from an `end` token returned by a previous request to this endpoint. + */ + to?: string; + /** + * The direction to return events from. If this is set to `f`, events + * will be returned in chronological order starting at `from`. If it + * is set to `b`, events will be returned in *reverse* chronological + * order, again starting at `from`. + */ + dir: "b" | "f"; + /** The maximum number of events to return. Default: 10. */ + limit?: number; + /** A JSON RoomEventFilter to filter returned events with. */ + filter?: string; + }; + }; + responses: { + /** A list of messages with a new token to request more. */ + 200: { + schema: { + /** + * @description A list of room events. The order depends on the `dir` parameter. + * For `dir=b` events will be in reverse-chronological order, + * for `dir=f` in chronological order. (The exact definition of `chronological` + * is dependent on the server implementation.) + * + * Note that an empty `chunk` does not *necessarily* imply that no more events + * are available. Clients should continue to paginate until no `end` property + * is returned. + */ + chunk: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * @description A token corresponding to the end of `chunk`. This token can be passed + * back to this endpoint to request further events. + * + * If no further events are available (either because we have + * reached the start of the timeline, or because the user does + * not have permission to see any more events), this property + * is omitted from the response. + */ + end?: string; + /** + * @description A token corresponding to the start of `chunk`. This will be the same as + * the value given in `from`. + */ + start: string; + /** + * @description A list of state events relevant to showing the `chunk`. For example, if + * `lazy_load_members` is enabled in the filter then this may contain + * the membership events for the senders of events in the `chunk`. + * + * Unless `include_redundant_members` is `true`, the server + * may remove membership events which would have already been + * sent to the client in prior calls to this endpoint, assuming + * the membership of those members has not changed. + */ + state?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + }; + }; + /** You aren't a member of the room. */ + 403: unknown; + }; + }; + /** + * Sets the position of the read marker for a given room, and optionally + * the read receipt's location. + */ + setReadMarker: { + parameters: { + path: { + /** The room ID to set the read marker in for the user. */ + roomId: string; + }; + body: { + /** The read marker and optional read receipt locations. */ + body: { + /** + * @description The event ID the read marker should be located at. The + * event MUST belong to the room. + * @example $somewhere:example.org + */ + "m.fully_read"?: string; + /** + * @description The event ID to set the read receipt location at. This is + * equivalent to calling `/receipt/m.read/$elsewhere:example.org` + * and is provided here to save that extra call. + * @example $elsewhere:example.org + */ + "m.read"?: string; + /** + * @description The event ID to set the *private* read receipt location at. This + * equivalent to calling `/receipt/m.read.private/$elsewhere:example.org` + * and is provided here to save that extra call. + * @example $elsewhere:example.org + */ + "m.read.private"?: string; + }; + }; + }; + responses: { + /** The read marker, and read receipt(s) if provided, have been updated. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This API updates the marker for the given receipt type to the event ID + * specified. + */ + postReceipt: { + parameters: { + path: { + /** The room in which to send the event. */ + roomId: string; + /** + * The type of receipt to send. This can also be `m.fully_read` as an + * alternative to [`/read_markers`](https://spec.matrix.org/v1.7/client-server-api/#post_matrixclientv3roomsroomidread_markers). + * + * Note that `m.fully_read` does not appear under `m.receipt`: this endpoint + * effectively calls `/read_markers` internally when presented with a receipt + * type of `m.fully_read`. + */ + receiptType: "m.read" | "m.read.private" | "m.fully_read"; + /** The event ID to acknowledge up to. */ + eventId: string; + }; + body: { + /** + * Extra receipt information to attach to `content` if any. The + * server will automatically set the `ts` field. + */ + receipt: { + /** + * @description The root thread event's ID (or `main`) for which + * thread this receipt is intended to be under. If + * not specified, the read receipt is *unthreaded* + * (default). + */ + thread_id?: string; + }; + }; + }; + responses: { + /** The receipt was sent. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The `thread_id` is invalid in some way. For example: + * * It is not a string. + * * It is empty. + * * It is provided for an incompatible receipt type. + * * The `event_id` is not related to the `thread_id`. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Strips all information out of an event which isn't critical to the + * integrity of the server-side representation of the room. + * + * This cannot be undone. + * + * Any user with a power level greater than or equal to the `m.room.redaction` + * event power level may send redaction events in the room. If the user's power + * level greater is also greater than or equal to the `redact` power level + * of the room, the user may redact events sent by other users. + * + * Server administrators may redact events sent by users on their server. + */ + redactEvent: { + parameters: { + path: { + /** The room from which to redact the event. */ + roomId: string; + /** The ID of the event to redact */ + eventId: string; + /** + * The [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers) for this event. Clients should generate a + * unique ID; it will be used by the server to ensure idempotency of requests. + */ + txnId: string; + }; + body: { + body: { + /** @description The reason for the event being redacted. */ + reason?: string; + }; + }; + }; + responses: { + /** An ID for the redaction event. */ + 200: { + schema: { + /** @description A unique identifier for the event. */ + event_id?: string; + }; + }; + }; + }; + /** + * Reports an event as inappropriate to the server, which may then notify + * the appropriate people. + */ + reportContent: { + parameters: { + path: { + /** The room in which the event being reported is located. */ + roomId: string; + /** The event to report. */ + eventId: string; + }; + body: { + body: { + /** @description The reason the content is being reported. May be blank. */ + reason?: string; + /** + * @description The score to rate this content as where -100 is most offensive + * and 0 is inoffensive. + */ + score?: number; + }; + }; + }; + responses: { + /** The event has been reported successfully. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** + * This endpoint is used to send a message event to a room. Message events + * allow access to historical events and pagination, making them suited + * for "once-off" activity in a room. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * [Room Events](https://spec.matrix.org/v1.7/client-server-api/#room-events) for the m. event specification. + */ + sendMessage: { + parameters: { + path: { + /** The room to send the event to. */ + roomId: string; + /** The type of event to send. */ + eventType: string; + /** + * The [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers) for this event. Clients should generate an + * ID unique across requests with the same access token; it will be + * used by the server to ensure idempotency of requests. + */ + txnId: string; + }; + body: { + body: { [key: string]: unknown }; + }; + }; + responses: { + /** An ID for the sent event. */ + 200: { + schema: { + /** @description A unique identifier for the event. */ + event_id: string; + }; + }; + /** + * The request is invalid. A [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned. As well as the normal common error codes, other reasons for rejection include: + * + * - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](https://spec.matrix.org/v1.7/client-server-api/#avoiding-duplicate-annotations). + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** Get the state events for the current state of a room. */ + getRoomState: { + parameters: { + path: { + /** The room to look up the state for. */ + roomId: string; + }; + }; + responses: { + /** The current state of the room */ + 200: { + schema: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + }; + /** You aren't a member of the room and weren't previously a member of the room. */ + 403: unknown; + }; + }; + /** + * Looks up the contents of a state event in a room. If the user is + * joined to the room then the state is taken from the current + * state of the room. If the user has left the room then the state is + * taken from the state of the room when they left. + */ + getRoomStateWithKey: { + parameters: { + path: { + /** The room to look up the state in. */ + roomId: string; + /** The type of state to look up. */ + eventType: string; + /** + * The key of the state to look up. Defaults to an empty string. When + * an empty string, the trailing slash on this endpoint is optional. + */ + stateKey: string; + }; + }; + responses: { + /** The content of the state event. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** You aren't a member of the room and weren't previously a member of the room. */ + 403: unknown; + /** The room has no state with the given type or key. */ + 404: unknown; + }; + }; + /** + * State events can be sent using this endpoint. These events will be + * overwritten if ``, `` and `` all + * match. + * + * Requests to this endpoint **cannot use transaction IDs** + * like other `PUT` paths because they cannot be differentiated from the + * `state_key`. Furthermore, `POST` is unsupported on state paths. + * + * The body of the request should be the content object of the event; the + * fields in this object will vary depending on the type of event. See + * [Room Events](https://spec.matrix.org/v1.7/client-server-api/#room-events) for the `m.` event specification. + * + * If the event type being sent is `m.room.canonical_alias` servers + * SHOULD ensure that any new aliases being listed in the event are valid + * per their grammar/syntax and that they point to the room ID where the + * state event is to be sent. Servers do not validate aliases which are + * being removed or are already present in the state event. + */ + setRoomStateWithKey: { + parameters: { + path: { + /** The room to set the state in */ + roomId: string; + /** The type of event to send. */ + eventType: string; + /** + * The state_key for the state to send. Defaults to the empty string. When + * an empty string, the trailing slash on this endpoint is optional. + */ + stateKey: string; + }; + body: { + body: { [key: string]: unknown }; + }; + }; + responses: { + /** An ID for the sent event. */ + 200: { + schema: { + /** @description A unique identifier for the event. */ + event_id: string; + }; + }; + /** + * The sender's request is malformed. + * + * Some example error codes include: + * + * * `M_INVALID_PARAM`: One or more aliases within the `m.room.canonical_alias` + * event have invalid syntax. + * + * * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event + * do not point to the room ID for which the state event is to be sent to. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The sender doesn't have permission to send the event into the room. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This tells the server that the user is typing for the next N + * milliseconds where N is the value specified in the `timeout` key. + * Alternatively, if `typing` is `false`, it tells the server that the + * user has stopped typing. + */ + setTyping: { + parameters: { + path: { + /** The user who has started to type. */ + userId: string; + /** The room in which the user is typing. */ + roomId: string; + }; + body: { + /** The current typing state. */ + typingState: { + /** @description The length of time in milliseconds to mark this user as typing. */ + timeout?: number; + /** + * @description Whether the user is typing or not. If `false`, the `timeout` + * key can be omitted. + */ + typing: boolean; + }; + }; + }; + responses: { + /** The new typing state was set. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Unban a user from the room. This allows them to be invited to the room, + * and join if they would otherwise be allowed to join according to its join rules. + * + * The caller must have the required power level in order to perform this operation. + */ + unban: { + parameters: { + path: { + /** The room identifier (not alias) from which the user should be unbanned. */ + roomId: string; + }; + body: { + body: { + /** + * @description Optional reason to be included as the `reason` on the subsequent + * membership event. + */ + reason?: string; + /** @description The fully qualified user ID of the user being unbanned. */ + user_id: string; + }; + }; + }; + responses: { + /** The user has been unbanned from the room. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are: + * + * - The unbanner's power level is insufficient to unban users from the room. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** Upgrades the given room to a particular room version. */ + upgradeRoom: { + parameters: { + path: { + /** The ID of the room to upgrade. */ + roomId: string; + }; + body: { + body: { + /** @description The new version for the room. */ + new_version: string; + }; + }; + }; + responses: { + /** The room was successfully upgraded. */ + 200: { + schema: { + /** @description The ID of the new room. */ + replacement_room: string; + }; + }; + /** + * The request was invalid. One way this can happen is if the room version + * requested is not supported by the homeserver. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The user is not permitted to upgrade the room. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** Performs a full text search across different categories. */ + search: { + parameters: { + query: { + /** + * The point to return events from. If given, this should be a + * `next_batch` result from a previous call to this endpoint. + */ + next_batch?: string; + }; + body: { + body: { + /** + * Categories + * @description Describes which categories to search in and their criteria. + */ + search_categories: { + /** + * Room Events Criteria + * @description Mapping of category name to search criteria. + */ + room_events?: { + /** + * Include Event Context + * @description Configures whether any context for the events + * returned are included in the response. + */ + event_context?: { + /** + * After limit + * @description How many events after the result are + * returned. By default, this is `5`. + */ + after_limit?: number; + /** + * Before limit + * @description How many events before the result are + * returned. By default, this is `5`. + */ + before_limit?: number; + /** + * Return profile information + * @description Requests that the server returns the + * historic profile information for the users + * that sent the events that were returned. + * By default, this is `false`. + */ + include_profile?: boolean; + }; + /** + * Filter + * @description This takes a [filter](https://spec.matrix.org/v1.7/client-server-api/#filtering). + */ + filter?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** + * Groupings + * @description Requests that the server partitions the result set + * based on the provided list of keys. + */ + groupings?: { + /** + * Groups + * @description List of groups to request. + */ + group_by?: { + /** + * Group Key + * @description Key that defines the group. + * @enum {string} + */ + key?: "room_id" | "sender"; + }[]; + }; + /** + * Include current state + * @description Requests the server return the current state for + * each room returned. + */ + include_state?: boolean; + /** @description The keys to search. Defaults to all. */ + keys?: ("content.body" | "content.name" | "content.topic")[]; + /** + * Ordering + * @description The order in which to search for results. + * By default, this is `"rank"`. + * @enum {string} + */ + order_by?: "recent" | "rank"; + /** @description The string to search events for */ + search_term: string; + }; + }; + }; + }; + }; + responses: { + /** Results of the search. */ + 200: { + schema: { + /** + * Result Categories + * @description Describes which categories to search in and their criteria. + */ + search_categories: { + /** + * Result Room Events + * @description Mapping of category name to search criteria. + */ + room_events?: { + /** @description An approximate count of the total number of results found. */ + count?: number; + /** + * Groups + * @description Any groups that were requested. + * + * The outer `string` key is the group key requested (eg: `room_id` + * or `sender`). The inner `string` key is the grouped value (eg: + * a room's ID or a user's ID). + */ + groups?: { + [key: string]: { + [key: string]: { + /** + * Next Batch in Group + * @description Token that can be used to get the next batch + * of results in the group, by passing as the + * `next_batch` parameter to the next call. If + * this field is absent, there are no more + * results in this group. + */ + next_batch?: string; + /** + * Group Order + * @description Key that can be used to order different + * groups. + */ + order?: number; + /** @description Which results are in this group. */ + results?: string[]; + }; + }; + }; + /** + * Highlights + * @description List of words which should be highlighted, useful for stemming which may change the query terms. + */ + highlights?: string[]; + /** + * Next Batch + * @description Token that can be used to get the next batch of + * results, by passing as the `next_batch` parameter to + * the next call. If this field is absent, there are no + * more results. + */ + next_batch?: string; + /** + * Results + * @description List of results in the requested order. + */ + results?: { + /** + * Event Context + * @description Context for result, if requested. + */ + context?: { + /** + * End Token + * @description Pagination token for the end of the chunk + */ + end?: string; + /** + * Events After + * @description Events just after the result. + */ + events_after?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * Events Before + * @description Events just before the result. + */ + events_before?: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + /** + * Profile Information + * @description The historic profile information of the + * users that sent the events returned. + * + * The `string` key is the user ID for which + * the profile belongs to. + */ + profile_info?: { + [key: string]: { + /** + * Avatar Url + * Format: uri + */ + avatar_url?: string; + /** Display name */ + displayname?: string; + }; + }; + /** + * Start Token + * @description Pagination token for the start of the chunk + */ + start?: string; + }; + /** @description A number that describes how closely this result matches the search. Higher is closer. */ + rank?: number; + /** + * Event + * @description The event that matched. + */ + result?: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + }; + }[]; + /** + * Current state + * @description The current state for every room in the results. + * This is included if the request had the + * `include_state` key set with a value of `true`. + * + * The `string` key is the room ID for which the `State + * Event` array belongs to. + */ + state?: { + [key: string]: ({ + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + } & { + /** + * @description The ID of the room associated with this event. + * @example !jEsUZKDJdhlrceRyVU:example.org + */ + room_id: string; + unsigned?: { + /** + * ClientEvent + * @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 + * } + * } + */ + redacted_because?: unknown; + }; + })[]; + }; + }; + }; + }; + }; + /** Part of the request was invalid. */ + 400: unknown; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This endpoint is used to send send-to-device events to a set of + * client devices. + */ + sendToDevice: { + parameters: { + path: { + /** The type of event to send. */ + eventType: string; + /** + * The [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers) for this event. Clients should generate an + * ID unique across requests with the same access token; it will be + * used by the server to ensure idempotency of requests. + */ + txnId: string; + }; + body: { + body: { + /** + * @description The messages to send. A map from user ID, to a map from + * device ID to message body. The device ID may also be `*`, + * meaning all known devices for the user. + * @example { + * "@alice:example.com": { + * "TLLBEANAAG": { + * "example_content_key": "value" + * } + * } + * } + */ + messages: { + [key: string]: { [key: string]: { [key: string]: unknown } }; + }; + }; + }; + }; + responses: { + /** The message was successfully sent. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** + * Synchronise the client's state with the latest state on the server. + * Clients use this API when they first log in to get an initial snapshot + * of the state on the server, and then continue to call this API to get + * incremental deltas to the state, and to receive new messages. + * + * *Note*: This endpoint supports lazy-loading. See [Filtering](https://spec.matrix.org/v1.7/client-server-api/#filtering) + * for more information. Lazy-loading members is only supported on a `StateFilter` + * for this endpoint. When lazy-loading is enabled, servers MUST include the + * syncing user's own membership event when they join a room, or when the + * full state of rooms is requested, to aid discovering the user's avatar & + * displayname. + * + * Further, like other members, the user's own membership event is eligible + * for being considered redundant by the server. When a sync is `limited`, + * the server MUST return membership events for events in the gap + * (between `since` and the start of the returned timeline), regardless + * as to whether or not they are redundant. This ensures that joins/leaves + * and profile changes which occur during the gap are not lost. + * + * Note that the default behaviour of `state` is to include all membership + * events, alongside other state, when lazy-loading is not enabled. + */ + sync: { + parameters: { + query: { + /** + * The ID of a filter created using the filter API or a filter JSON + * object encoded as a string. The server will detect whether it is + * an ID or a JSON object by whether the first character is a `"{"` + * open brace. Passing the JSON inline is best suited to one off + * requests. Creating a filter using the filter API is recommended for + * clients that reuse the same filter multiple times, for example in + * long poll requests. + * + * See [Filtering](https://spec.matrix.org/v1.7/client-server-api/#filtering) for more information. + */ + filter?: string; + /** + * A point in time to continue a sync from. This should be the + * `next_batch` token returned by an earlier call to this endpoint. + */ + since?: string; + /** + * Controls whether to include the full state for all rooms the user + * is a member of. + * + * If this is set to `true`, then all state events will be returned, + * even if `since` is non-empty. The timeline will still be limited + * by the `since` parameter. In this case, the `timeout` parameter + * will be ignored and the query will return immediately, possibly with + * an empty timeline. + * + * If `false`, and `since` is non-empty, only state which has + * changed since the point indicated by `since` will be returned. + * + * By default, this is `false`. + */ + full_state?: boolean; + /** + * Controls whether the client is automatically marked as online by + * polling this API. If this parameter is omitted then the client is + * automatically marked as online when it uses this API. Otherwise if + * the parameter is set to "offline" then the client is not marked as + * being online when it uses this API. When set to "unavailable", the + * client is marked as being idle. + */ + set_presence?: "offline" | "online" | "unavailable"; + /** + * The maximum time to wait, in milliseconds, before returning this + * request. If no events (or other data) become available before this + * time elapses, the server will return a response with empty fields. + * + * By default, this is `0`, so the server will return immediately + * even if the response is empty. + */ + timeout?: number; + }; + }; + responses: { + /** The initial snapshot or delta for the client to use to update their state. */ + 200: { + schema: { + /** + * Account Data + * @description The global private data created by this user. + */ + account_data?: { + /** @description List of events. */ + events?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + }; + /** + * DeviceLists + * @description Information on end-to-end device updates, as specified in + * [End-to-end encryption](https://spec.matrix.org/v1.7/client-server-api/#e2e-extensions-to-sync). + */ + device_lists?: { [key: string]: unknown }; + /** + * One-time keys count + * @description Information on end-to-end encryption keys, as specified + * in [End-to-end encryption](https://spec.matrix.org/v1.7/client-server-api/#e2e-extensions-to-sync). + */ + device_one_time_keys_count?: { [key: string]: number }; + /** + * @description The batch token to supply in the `since` param of the next + * `/sync` request. + */ + next_batch: string; + /** + * Presence + * @description The updates to the presence status of other users. + */ + presence?: { + /** @description List of events. */ + events?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + }; + /** + * Rooms + * @description Updates to rooms. + */ + rooms?: { + /** + * Invited Rooms + * @description The rooms that the user has been invited to, mapped as room ID to + * room information. + */ + invite?: { + [key: string]: { + /** + * InviteState + * @description The [stripped state](#stripped-state) of a room that the user has been invited + * to. + */ + invite_state?: { + /** @description The [stripped state events](#stripped-state) that form the invite state. */ + events?: { + /** + * EventContent + * @description The `content` for the event. + */ + content: { [key: string]: unknown }; + /** @description The `sender` for the event. */ + sender: string; + /** @description The `state_key` for the event. */ + state_key: string; + /** @description The `type` for the event. */ + type: string; + }[]; + }; + }; + }; + /** + * Joined Rooms + * @description The rooms that the user has joined, mapped as room ID to + * room information. + */ + join?: { + [key: string]: { + /** + * Account Data + * @description The private data that this user has attached to + * this room. + */ + account_data?: { + /** @description List of events. */ + events?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + }; + /** + * Ephemeral + * @description The new ephemeral events in the room (events that + * aren't recorded in the timeline or state of the + * room). In this version of the spec, these are + * [typing notification](#typing-notifications) and + * [read receipt](#receipts) events. + */ + ephemeral?: { + /** @description List of events. */ + events?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + }; + /** + * State + * @description Updates to the state, between the time indicated by + * the `since` parameter, and the start of the + * `timeline` (or all state up to the start of the + * `timeline`, if `since` is not given, or + * `full_state` is true). + * + * N.B. state updates for `m.room.member` events will + * be incomplete if `lazy_load_members` is enabled in + * the `/sync` filter, and only return the member events + * required to display the senders of the timeline events + * in this response. + */ + state?: { + /** @description List of events. */ + events?: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + }[]; + }; + /** + * RoomSummary + * @description Information about the room which clients may need to + * correctly render it to users. + */ + summary?: { + /** + * @description The users which can be used to generate a room name + * if the room does not have one. Required if the room's + * `m.room.name` or `m.room.canonical_alias` state events + * are unset or empty. + * + * This should be the first 5 members of the room, ordered + * by stream ordering, which are joined or invited. The + * list must never include the client's own user ID. When + * no joined or invited members are available, this should + * consist of the banned and left users. More than 5 members + * may be provided, however less than 5 should only be provided + * when there are less than 5 members to represent. + * + * When lazy-loading room members is enabled, the membership + * events for the heroes MUST be included in the `state`, + * unless they are redundant. When the list of users changes, + * the server notifies the client by sending a fresh list of + * heroes. If there are no changes since the last sync, this + * field may be omitted. + */ + "m.heroes"?: string[]; + /** + * @description The number of users with `membership` of `invite`. + * If this field has not changed since the last sync, it + * may be omitted. Required otherwise. + */ + "m.invited_member_count"?: number; + /** + * @description The number of users with `membership` of `join`, + * including the client's own user ID. If this field has + * not changed since the last sync, it may be omitted. + * Required otherwise. + */ + "m.joined_member_count"?: number; + }; + /** + * Timeline + * @description The timeline of messages and state changes in the + * room. + */ + timeline?: { + /** @description List of events. */ + events: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + }[]; + /** @description True if the number of events returned was limited by the `limit` on the filter. */ + limited?: boolean; + /** + * @description A token that can be supplied to the `from` parameter of the [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) endpoint in order to retrieve earlier events. + * If no earlier events are available, this property may be omitted from the response. + */ + prev_batch?: string; + }; + /** + * Unread Notification Counts + * @description Counts of unread notifications for this room. See the + * [Receiving notifications](https://spec.matrix.org/v1.7/client-server-api/#receiving-notifications) section + * for more information on how these are calculated. + * + * If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + * these counts will only be for the main timeline rather than all events in the room. + * See the [threading module](#threading) for more information. + */ + unread_notifications?: { + /** + * Highlighted notification count + * @description The number of unread notifications for this room with the highlight flag set. + */ + highlight_count?: number; + /** + * Total notification count + * @description The total number of unread notifications for this room. + */ + notification_count?: number; + }; + /** + * Unread Thread Notification Counts + * @description If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + * the notification counts for each [thread](#threading) in this room. The object is + * keyed by thread root ID, with values matching `unread_notifications`. + * + * If a thread does not have any notifications it can be omitted from this object. If + * no threads have notification counts, this whole object can be omitted. + */ + unread_thread_notifications?: { + [key: string]: { + /** + * ThreadedHighlightNotificationCount + * @description The number of unread notifications for this *thread* with the highlight flag set. + */ + highlight_count?: number; + /** + * ThreadedTotalNotificationCount + * @description The total number of unread notifications for this *thread*. + */ + notification_count?: number; + }; + }; + }; + }; + /** + * Knocked rooms + * @description The rooms that the user has knocked upon, mapped as room ID to room information. + */ + knock?: { + [key: string]: { + /** + * KnockState + * @description The [stripped state](#stripped-state) of a room that the user has knocked upon. + */ + knock_state?: { + /** @description The [stripped state events](#stripped-state) that form the knock state. */ + events?: { + /** + * EventContent + * @description The `content` for the event. + */ + content: { [key: string]: unknown }; + /** @description The `sender` for the event. */ + sender: string; + /** @description The `state_key` for the event. */ + state_key: string; + /** @description The `type` for the event. */ + type: string; + }[]; + }; + }; + }; + /** + * Left rooms + * @description The rooms that the user has left or been banned from, mapped as room ID to + * room information. + */ + leave?: { + [key: string]: { + /** + * Account Data + * @description The private data that this user has attached to + * this room. + */ + account_data?: { + /** @description List of events. */ + events?: { + /** @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. */ + content: { [key: string]: unknown }; + /** @description The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type' */ + type: string; + }[]; + }; + /** + * State + * @description The state updates for the room up to the start of the timeline. + */ + state?: { + /** @description List of events. */ + events?: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + }[]; + }; + /** + * Timeline + * @description The timeline of messages and state changes in the + * room up to the point when the user left. + */ + timeline?: { + /** @description List of events. */ + events: { + /** + * @description The body of this event, as created by the client which sent it. + * @example { + * "membership": "join" + * } + */ + content: { [key: string]: unknown }; + /** + * @description The globally unique identifier for this event. + * @example $26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45 + */ + event_id: string; + /** + * Format: int64 + * @description Timestamp (in milliseconds since the unix epoch) on originating homeserver + * when this event was sent. + * @example 1632489532305 + */ + origin_server_ts: number; + /** + * @description Contains the fully-qualified ID of the user who sent this event. + * @example @example:example.org + */ + sender: string; + /** + * @description Present if, and only if, this event is a *state* event. The key making + * this piece of state unique in the room. Note that it is often an empty + * string. + * + * State keys starting with an `@` are reserved for referencing user IDs, such + * as room members. With the exception of a few events, state events set with a + * given user's ID as the state key MUST only be set by that user. + * @example @user:example.org + */ + state_key?: string; + /** + * @description The type of the event. + * @example m.room.member + */ + type: string; + /** + * UnsignedData + * @description Contains optional extra information about the event. + */ + unsigned?: { + /** + * Format: int64 + * @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 + */ + age?: number; + /** + * EventContent + * @description The previous `content` for this event. This field is generated + * by the local homeserver, and is only returned if the event is a state event, + * and the client has permission to see the previous content. + */ + prev_content?: { [key: string]: unknown }; + /** + * ClientEventWithoutRoomID + * @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 + * } + * } + */ + redacted_because?: { [key: string]: unknown }; + /** + * @description The client-supplied [transaction ID](https://spec.matrix.org/v1.7/client-server-api/#transaction-identifiers), for example, provided via + * `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, + * if the client being given the event is the same one which sent it. + */ + transaction_id?: string; + }; + }[]; + /** @description True if the number of events returned was limited by the `limit` on the filter. */ + limited?: boolean; + /** + * @description A token that can be supplied to the `from` parameter of the [`/rooms//messages`](#get_matrixclientv3roomsroomidmessages) endpoint in order to retrieve earlier events. + * If no earlier events are available, this property may be omitted from the response. + */ + prev_batch?: string; + }; + }; + }; + }; + /** + * ToDevice + * @description Information on the send-to-device messages for the client + * device, as defined in [Send-to-Device messaging](https://spec.matrix.org/v1.7/client-server-api/#extensions-to-sync). + */ + to_device?: { [key: string]: unknown }; + }; + }; + }; + }; + /** + * Retrieve an array of third-party network locations from a Matrix room + * alias. + */ + queryLocationByAlias: { + parameters: { + query: { + /** The Matrix room alias to look up. */ + alias: string; + }; + }; + responses: { + /** All found third-party locations. */ + 200: { + schema: { + /** + * @description An alias for a matrix room. + * @example #freenode_#matrix:matrix.org + */ + alias: string; + /** + * @description Information used to identify this third-party location. + * @example { + * "channel": "#matrix", + * "network": "freenode" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description The protocol ID that the third-party location is a part of. + * @example irc + */ + protocol: string; + }[]; + }; + /** The Matrix room alias was not found */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Requesting this endpoint with a valid protocol name results in a list + * of successful mapping results in a JSON array. Each result contains + * objects to represent the Matrix room or rooms that represent a portal + * to this third-party network. Each has the Matrix room alias string, + * an identifier for the particular third-party network protocol, and an + * object containing the network-specific fields that comprise this + * identifier. It should attempt to canonicalise the identifier as much + * as reasonably possible given the network type. + */ + queryLocationByProtocol: { + parameters: { + path: { + /** The protocol used to communicate to the third-party network. */ + protocol: string; + }; + query: { + /** + * One or more custom fields to help identify the third-party + * location. + */ + searchFields?: string; + }; + }; + responses: { + /** At least one portal room was found. */ + 200: { + schema: { + /** + * @description An alias for a matrix room. + * @example #freenode_#matrix:matrix.org + */ + alias: string; + /** + * @description Information used to identify this third-party location. + * @example { + * "channel": "#matrix", + * "network": "freenode" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description The protocol ID that the third-party location is a part of. + * @example irc + */ + protocol: string; + }[]; + }; + /** No portal rooms were found. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** Fetches the metadata from the homeserver about a particular third-party protocol. */ + getProtocolMetadata: { + parameters: { + path: { + /** The name of the protocol. */ + protocol: string; + }; + }; + responses: { + /** The protocol was found and metadata returned. */ + 200: { + schema: { + /** + * Field Types + * @description The type definitions for the fields defined in the `user_fields` and + * `location_fields`. Each entry in those arrays MUST have an entry here. The + * `string` key for this object is field name itself. + * + * May be an empty object if no fields are defined. + * @example { + * "channel": { + * "placeholder": "#foobar", + * "regexp": "#[^\\s]+" + * }, + * "network": { + * "placeholder": "irc.example.org", + * "regexp": "([a-z0-9]+\\.)*[a-z0-9]+" + * }, + * "nickname": { + * "placeholder": "username", + * "regexp": "[^\\s#]+" + * } + * } + */ + field_types: { + fieldname: unknown; + } & { + [key: string]: { + /** @description An placeholder serving as a valid example of the field value. */ + placeholder: string; + /** + * @description A regular expression for validation of a field's value. This may be relatively + * coarse to verify the value as the application service providing this protocol + * may apply additional validation or filtering. + */ + regexp: string; + }; + }; + /** + * @description A content URI representing an icon for the third-party protocol. + * @example mxc://example.org/aBcDeFgH + */ + icon: string; + /** + * @description A list of objects representing independent instances of configuration. + * For example, multiple networks on IRC if multiple are provided by the + * same application service. + */ + instances: { + /** + * @description A human-readable description for the protocol, such as the name. + * @example Freenode + */ + desc: string; + /** + * @description Preset values for `fields` the client may use to search by. + * @example { + * "network": "freenode" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description An optional content URI representing the protocol. Overrides the one provided + * at the higher level Protocol object. + * @example mxc://example.org/JkLmNoPq + */ + icon?: string; + /** + * @description A unique identifier across all instances. + * @example freenode + */ + network_id: string; + }[]; + /** + * @description Fields which may be used to identify a third-party location. These should be + * ordered to suggest the way that entities may be grouped, where higher + * groupings are ordered first. For example, the name of a network should be + * searched before the name of a channel. + * @example [ + * "network", + * "channel" + * ] + */ + location_fields: string[]; + /** + * @description Fields which may be used to identify a third-party user. These should be + * ordered to suggest the way that entities may be grouped, where higher + * groupings are ordered first. For example, the name of a network should be + * searched before the nickname of a user. + * @example [ + * "network", + * "nickname" + * ] + */ + user_fields: string[]; + }; + }; + /** The protocol is unknown. */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Fetches the overall metadata about protocols supported by the + * homeserver. Includes both the available protocols and all fields + * required for queries against each protocol. + */ + getProtocols: { + responses: { + /** The protocols supported by the homeserver. */ + 200: { + schema: { + [key: string]: { + /** + * Field Types + * @description The type definitions for the fields defined in the `user_fields` and + * `location_fields`. Each entry in those arrays MUST have an entry here. The + * `string` key for this object is field name itself. + * + * May be an empty object if no fields are defined. + * @example { + * "channel": { + * "placeholder": "#foobar", + * "regexp": "#[^\\s]+" + * }, + * "network": { + * "placeholder": "irc.example.org", + * "regexp": "([a-z0-9]+\\.)*[a-z0-9]+" + * }, + * "nickname": { + * "placeholder": "username", + * "regexp": "[^\\s#]+" + * } + * } + */ + field_types: { + fieldname: unknown; + } & { + [key: string]: { + /** @description An placeholder serving as a valid example of the field value. */ + placeholder: string; + /** + * @description A regular expression for validation of a field's value. This may be relatively + * coarse to verify the value as the application service providing this protocol + * may apply additional validation or filtering. + */ + regexp: string; + }; + }; + /** + * @description A content URI representing an icon for the third-party protocol. + * @example mxc://example.org/aBcDeFgH + */ + icon: string; + /** + * @description A list of objects representing independent instances of configuration. + * For example, multiple networks on IRC if multiple are provided by the + * same application service. + */ + instances: { + /** + * @description A human-readable description for the protocol, such as the name. + * @example Freenode + */ + desc: string; + /** + * @description Preset values for `fields` the client may use to search by. + * @example { + * "network": "freenode" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description An optional content URI representing the protocol. Overrides the one provided + * at the higher level Protocol object. + * @example mxc://example.org/JkLmNoPq + */ + icon?: string; + /** + * @description A unique identifier across all instances. + * @example freenode + */ + network_id: string; + }[]; + /** + * @description Fields which may be used to identify a third-party location. These should be + * ordered to suggest the way that entities may be grouped, where higher + * groupings are ordered first. For example, the name of a network should be + * searched before the name of a channel. + * @example [ + * "network", + * "channel" + * ] + */ + location_fields: string[]; + /** + * @description Fields which may be used to identify a third-party user. These should be + * ordered to suggest the way that entities may be grouped, where higher + * groupings are ordered first. For example, the name of a network should be + * searched before the nickname of a user. + * @example [ + * "network", + * "nickname" + * ] + */ + user_fields: string[]; + }; + }; + }; + }; + }; + /** Retrieve an array of third-party users from a Matrix User ID. */ + queryUserByID: { + parameters: { + query: { + /** The Matrix User ID to look up. */ + userid: string; + }; + }; + responses: { + /** An array of third-party users. */ + 200: { + schema: { + /** + * @description Information used to identify this third-party location. + * @example { + * "user": "jim" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description The protocol ID that the third-party location is a part of. + * @example gitter + */ + protocol: string; + /** + * @description A Matrix User ID represting a third-party user. + * @example @_gitter_jim:matrix.org + */ + userid: string; + }[]; + }; + /** The Matrix User ID was not found */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Retrieve a Matrix User ID linked to a user on the third-party service, given + * a set of user parameters. + */ + queryUserByProtocol: { + parameters: { + path: { + /** The name of the protocol. */ + protocol: string; + }; + query: { + /** One or more custom fields that are passed to the AS to help identify the user. */ + "fields..."?: string; + }; + }; + responses: { + /** The Matrix User IDs found with the given parameters. */ + 200: { + schema: { + /** + * @description Information used to identify this third-party location. + * @example { + * "user": "jim" + * } + */ + fields: { [key: string]: unknown }; + /** + * @description The protocol ID that the third-party location is a part of. + * @example gitter + */ + protocol: string; + /** + * @description A Matrix User ID represting a third-party user. + * @example @_gitter_jim:matrix.org + */ + userid: string; + }[]; + }; + /** The Matrix User ID was not found */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Get some account data for the client. This config is only visible to the user + * that set the account data. + */ + getAccountData: { + parameters: { + path: { + /** + * The ID of the user to get account data for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** + * The event type of the account data to get. Custom types should be + * namespaced to avoid clashes. + */ + type: string; + }; + }; + responses: { + /** The account data content for the given type. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The access token provided is not authorized to retrieve this user's account + * data. Errcode: `M_FORBIDDEN`. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * No account data has been provided for this user with the given `type`. + * Errcode: `M_NOT_FOUND`. + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Set some account data for the client. This config is only visible to the user + * that set the account data. The config will be available to clients through the + * top-level `account_data` field in the homeserver response to + * [/sync](#get_matrixclientv3sync). + */ + setAccountData: { + parameters: { + path: { + /** + * The ID of the user to set account data for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** + * The event type of the account data to set. Custom types should be + * namespaced to avoid clashes. + */ + type: string; + }; + body: { + /** The content of the account data. */ + content: { [key: string]: unknown }; + }; + }; + responses: { + /** The account data was successfully added. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The request body is not a JSON object. Errcode: `M_BAD_JSON` + * or `M_NOT_JSON`. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The access token provided is not authorized to modify this user's account + * data. Errcode: `M_FORBIDDEN`. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * This `type` of account data is controlled by the server; it cannot be + * modified by clients. Errcode: `M_BAD_JSON`. + */ + 405: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Uploads a new filter definition to the homeserver. + * Returns a filter ID that may be used in future requests to + * restrict which events are returned to the client. + */ + defineFilter: { + parameters: { + path: { + /** The id of the user uploading the filter. The access token must be authorized to make requests for this user id. */ + userId: string; + }; + body: { + /** The filter to upload. */ + filter: { + /** @description The user account data that isn't associated with rooms to include. */ + account_data?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + }; + /** @description List of event fields to include. If this list is absent then all fields are included. The entries are [dot-separated paths for each property](https://spec.matrix.org/v1.7/appendices#dot-separated-property-paths) to include. So ['content.body'] will include the 'body' field of the 'content' object. A server may include more fields than were requested. */ + event_fields?: string[]; + /** + * @description The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as received over federation. The default is 'client'. + * @enum {string} + */ + event_format?: "client" | "federation"; + /** @description The presence updates to include. */ + presence?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + }; + /** + * RoomFilter + * @description Filters to be applied to room data. + */ + room?: { + /** @description The per user account data to include for rooms. */ + account_data?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description The ephemeral events to include for rooms. These are the events that appear in the `ephemeral` property in the `/sync` response. */ + ephemeral?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description Include rooms that the user has left in the sync, default false */ + include_leave?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data` */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data` */ + rooms?: string[]; + /** + * StateFilter + * @description The state events to include for rooms. + */ + state?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description The message and state update events to include for rooms. */ + timeline?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + }; + }; + }; + }; + responses: { + /** The filter was created. */ + 200: { + schema: { + /** + * @description The ID of the filter that was created. Cannot start + * with a `{` as this character is used to determine + * if the filter provided is inline JSON or a previously + * declared filter by homeservers on some APIs. + * @example 66696p746572 + */ + filter_id: string; + }; + }; + }; + }; + getFilter: { + parameters: { + path: { + /** The user ID to download a filter for. */ + userId: string; + /** The filter ID to download. */ + filterId: string; + }; + }; + responses: { + /** The filter definition. */ + 200: { + schema: { + /** @description The user account data that isn't associated with rooms to include. */ + account_data?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + }; + /** @description List of event fields to include. If this list is absent then all fields are included. The entries are [dot-separated paths for each property](https://spec.matrix.org/v1.7/appendices#dot-separated-property-paths) to include. So ['content.body'] will include the 'body' field of the 'content' object. A server may include more fields than were requested. */ + event_fields?: string[]; + /** + * @description The format to use for events. 'client' will return the events in a format suitable for clients. 'federation' will return the raw event as received over federation. The default is 'client'. + * @enum {string} + */ + event_format?: "client" | "federation"; + /** @description The presence updates to include. */ + presence?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + }; + /** + * RoomFilter + * @description Filters to be applied to room data. + */ + room?: { + /** @description The per user account data to include for rooms. */ + account_data?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description The ephemeral events to include for rooms. These are the events that appear in the `ephemeral` property in the `/sync` response. */ + ephemeral?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description Include rooms that the user has left in the sync, default false */ + include_leave?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data` */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in `ephemeral`, `state`, `timeline` or `account_data` */ + rooms?: string[]; + /** + * StateFilter + * @description The state events to include for rooms. + */ + state?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + /** @description The message and state update events to include for rooms. */ + timeline?: { + /** + * @description The maximum number of events to return, must be an integer greater than 0. + * + * Servers should apply a default value, and impose a maximum value to avoid + * resource exhaustion. + */ + limit?: number; + /** @description A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the `'senders'` filter. */ + not_senders?: string[]; + /** @description A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the `'types'` filter. A '*' can be used as a wildcard to match any sequence of characters. */ + not_types?: string[]; + /** @description A list of senders IDs to include. If this list is absent then all senders are included. */ + senders?: string[]; + /** @description A list of event types to include. If this list is absent then all event types are included. A `'*'` can be used as a wildcard to match any sequence of characters. */ + types?: string[]; + } & { + /** @description If `true`, includes only events with a `url` key in their content. If `false`, excludes those events. If omitted, `url` key is not considered for filtering. */ + contains_url?: boolean; + /** + * @description If `true`, sends all membership events for all events, even if they have already + * been sent to the client. Does not + * apply unless `lazy_load_members` is `true`. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + include_redundant_members?: boolean; + /** + * @description If `true`, enables lazy-loading of membership events. See + * [Lazy-loading room members](https://spec.matrix.org/v1.7/client-server-api/#lazy-loading-room-members) + * for more information. Defaults to `false`. + */ + lazy_load_members?: boolean; + /** @description A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the `'rooms'` filter. */ + not_rooms?: string[]; + /** @description A list of room IDs to include. If this list is absent then all rooms are included. */ + rooms?: string[]; + /** + * @description If `true`, enables per-[thread](https://spec.matrix.org/v1.7/client-server-api/#threading) notification + * counts. Only applies to the `/sync` endpoint. Defaults to `false`. + */ + unread_thread_notifications?: boolean; + }; + }; + }; + }; + /** Unknown filter. */ + 404: unknown; + }; + }; + /** + * Gets an OpenID token object that the requester may supply to another + * service to verify their identity in Matrix. The generated token is only + * valid for exchanging for user information from the federation API for + * OpenID. + * + * The access token generated is only valid for the OpenID API. It cannot + * be used to request another OpenID access token or call `/sync`, for + * example. + */ + requestOpenIdToken: { + parameters: { + path: { + /** + * The user to request an OpenID token for. Should be the user who + * is authenticated for the request. + */ + userId: string; + }; + body: { + /** An empty object. Reserved for future expansion. */ + body: { [key: string]: unknown }; + }; + }; + responses: { + /** + * OpenID token information. This response is nearly compatible with the + * response documented in the + * [OpenID Connect 1.0 Specification](http://openid.net/specs/openid-connect-core-1_0.html#TokenResponse) + * with the only difference being the lack of an `id_token`. Instead, + * the Matrix homeserver's name is provided. + */ + 200: { + schema: { + /** + * @description An access token the consumer may use to verify the identity of + * the person who generated the token. This is given to the federation + * API `GET /openid/userinfo` to verify the user's identity. + */ + access_token: string; + /** + * @description The number of seconds before this token expires and a new one must + * be generated. + */ + expires_in: number; + /** + * @description The homeserver domain the consumer should use when attempting to + * verify the user's identity. + */ + matrix_server_name: string; + /** @description The string `Bearer`. */ + token_type: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Get some account data for the client on a given room. This config is only + * visible to the user that set the account data. + */ + getAccountDataPerRoom: { + parameters: { + path: { + /** + * The ID of the user to get account data for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** The ID of the room to get account data for. */ + roomId: string; + /** + * The event type of the account data to get. Custom types should be + * namespaced to avoid clashes. + */ + type: string; + }; + }; + responses: { + /** The account data content for the given type. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** The given `roomID` is not a valid room ID. Errcode: `M_INVALID_PARAM`. */ + 400: unknown; + /** + * The access token provided is not authorized to retrieve this user's account + * data. Errcode: `M_FORBIDDEN`. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * No account data has been provided for this user and this room with the + * given `type`. Errcode: `M_NOT_FOUND`. + */ + 404: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Set some account data for the client on a given room. This config is only + * visible to the user that set the account data. The config will be delivered to + * clients in the per-room entries via [/sync](#get_matrixclientv3sync). + */ + setAccountDataPerRoom: { + parameters: { + path: { + /** + * The ID of the user to set account data for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** The ID of the room to set account data on. */ + roomId: string; + /** + * The event type of the account data to set. Custom types should be + * namespaced to avoid clashes. + */ + type: string; + }; + body: { + /** The content of the account data. */ + content: { [key: string]: unknown }; + }; + }; + responses: { + /** The account data was successfully added. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The request body is not a JSON object (errcode `M_BAD_JSON` or + * `M_NOT_JSON`), or the given `roomID` is not a valid room ID + * (errcode `M_INVALID_PARAM`). + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The access token provided is not authorized to modify this user's account + * data. Errcode: `M_FORBIDDEN`. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * This `type` of account data is controlled by the server; it cannot be + * modified by clients. Errcode: `M_BAD_JSON`. + */ + 405: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** List the tags set by a user on a room. */ + getRoomTags: { + parameters: { + path: { + /** + * The id of the user to get tags for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** The ID of the room to get tags for. */ + roomId: string; + }; + }; + responses: { + /** The list of tags for the user for the room. */ + 200: { + schema: { + tags?: { + [key: string]: { + /** + * Format: float + * @description A number in a range `[0,1]` describing a relative + * position of the room under the given tag. + */ + order?: number; + } & { [key: string]: unknown }; + }; + }; + }; + }; + }; + /** Add a tag to the room. */ + setRoomTag: { + parameters: { + path: { + /** + * The id of the user to add a tag for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** The ID of the room to add a tag to. */ + roomId: string; + /** The tag to add. */ + tag: string; + }; + body: { + /** Extra data for the tag, e.g. ordering. */ + body: { + /** + * Format: float + * @description A number in a range `[0,1]` describing a relative + * position of the room under the given tag. + */ + order?: number; + } & { [key: string]: unknown }; + }; + }; + responses: { + /** The tag was successfully added. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** Remove a tag from the room. */ + deleteRoomTag: { + parameters: { + path: { + /** + * The id of the user to remove a tag for. The access token must be + * authorized to make requests for this user ID. + */ + userId: string; + /** The ID of the room to remove a tag from. */ + roomId: string; + /** The tag to remove. */ + tag: string; + }; + }; + responses: { + /** The tag was successfully removed. */ + 200: { + schema: { [key: string]: unknown }; + }; + }; + }; + /** + * Performs a search for users. The homeserver may + * determine which subset of users are searched, however the homeserver + * MUST at a minimum consider the users the requesting user shares a + * room with and those who reside in public rooms (known to the homeserver). + * The search MUST consider local users to the homeserver, and SHOULD + * query remote users as part of the search. + * + * The search is performed case-insensitively on user IDs and display + * names preferably using a collation determined based upon the + * `Accept-Language` header provided in the request, if present. + */ + searchUserDirectory: { + parameters: { + body: { + body: { + /** + * @description The maximum number of results to return. Defaults to 10. + * @example 10 + */ + limit?: number; + /** + * @description The term to search for + * @example foo + */ + search_term: string; + }; + }; + }; + responses: { + /** The results of the search. */ + 200: { + schema: { + /** @description Indicates if the result list has been truncated by the limit. */ + limited: boolean; + /** @description Ordered by rank and then whether or not profile info is available. */ + results: { + /** + * Format: uri + * @description The avatar url, as an [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris), if one exists. + * @example mxc://bar.com/foo + */ + avatar_url?: string; + /** + * @description The display name of the user, if one exists. + * @example Foo + */ + display_name?: string; + /** + * @description The user's matrix user ID. + * @example @foo:bar.com + */ + user_id: string; + }[]; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This API provides credentials for the client to use when initiating + * calls. + */ + getTurnServer: { + responses: { + /** The TURN server credentials. */ + 200: { + schema: { + /** @description The password to use. */ + password: string; + /** @description The time-to-live in seconds */ + ttl: number; + /** @description A list of TURN URIs */ + uris: string[]; + /** @description The username to use. */ + username: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Gets the versions of the specification supported by the server. + * + * Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See + * [the Specification Versioning](../#specification-versions) for more + * information. + * + * The server may additionally advertise experimental features it supports + * through `unstable_features`. These features should be namespaced and + * may optionally include version information within their name if desired. + * Features listed here are not for optionally toggling parts of the Matrix + * specification and should only be used to advertise support for a feature + * which has not yet landed in the spec. For example, a feature currently + * undergoing the proposal process may appear here and eventually be taken + * off this list once the feature lands in the spec and the server deems it + * reasonable to do so. Servers may wish to keep advertising features here + * after they've been released into the spec to give clients a chance to + * upgrade appropriately. Additionally, clients should avoid using unstable + * features in their stable releases. + */ + getVersions: { + responses: { + /** The versions supported by the server. */ + 200: { + schema: { + /** + * @description Experimental features the server supports. Features not listed here, + * or the lack of this property all together, indicate that a feature is + * not supported. + */ + unstable_features?: { [key: string]: boolean }; + /** @description The supported versions. */ + versions: string[]; + }; + }; + }; + }; + /** + * Creates a new `mxc://` URI, independently of the content being uploaded. The content must be provided later + * via [`PUT /_matrix/media/v3/upload/{serverName}/{mediaId}`](https://spec.matrix.org/v1.7/client-server-api/#put_matrixmediav3uploadservernamemediaid). + * + * The server may optionally enforce a maximum age for unused IDs, + * and delete media IDs when the client doesn't start the upload in time, + * or when the upload was interrupted and not resumed in time. The server + * should include the maximum POSIX millisecond timestamp to complete the + * upload in the `unused_expires_at` field in the response JSON. The + * recommended default expiration is 24 hours which should be enough time + * to accommodate users on poor connection who find a better connection to + * complete the upload. + * + * As well as limiting the rate of requests to create `mxc://` URIs, the server + * should limit the number of concurrent *pending media uploads* a given + * user can have. A pending media upload is a created `mxc://` URI where (a) + * the media has not yet been uploaded, and (b) has not yet expired (the + * `unused_expires_at` timestamp has not yet passed). In both cases, the + * server should respond with an HTTP 429 error with an errcode of + * `M_LIMIT_EXCEEDED`. + */ + createContent: { + parameters: {}; + responses: { + /** The [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris) for the uploaded content. */ + 200: { + schema: { + /** + * Format: uri + * @description The [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris) at + * which the content will be available, once it is uploaded. + * @example mxc://example.com/AQwafuaFswefuhsfAFAgsw + */ + content_uri: string; + /** + * Format: int64 + * @description The timestamp (in milliseconds since the unix epoch) when the + * generated media id will expire, if media is not uploaded. + * @example 1647257217083 + */ + unused_expires_at?: number; + }; + }; + /** The user does not have permission to upload the content. */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This endpoint allows clients to retrieve the configuration of the content + * repository, such as upload limitations. + * Clients SHOULD use this as a guide when using content repository endpoints. + * All values are intentionally left optional. Clients SHOULD follow + * the advice given in the field description when the field is not available. + * + * **NOTE:** Both clients and server administrators should be aware that proxies + * between the client and the server may affect the apparent behaviour of content + * repository APIs, for example, proxies may enforce a lower upload size limit + * than is advertised by the server on this endpoint. + */ + getConfig: { + responses: { + /** The public content repository configuration for the matrix server. */ + 200: { + schema: { + /** + * Format: int64 + * @description The maximum size an upload can be in bytes. + * Clients SHOULD use this as a guide when uploading content. + * If not listed or null, the size limit should be treated as unknown. + */ + "m.upload.size"?: number; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + getContent: { + parameters: { + path: { + /** The server name from the `mxc://` URI (the authoritory component) */ + serverName: string; + /** The media ID from the `mxc://` URI (the path component) */ + mediaId: string; + }; + query: { + /** + * Indicates to the server that it should not attempt to fetch the media if it is deemed + * remote. This is to prevent routing loops where the server contacts itself. Defaults to + * true if not provided. + */ + allow_remote?: boolean; + /** + * The maximum number of milliseconds that the client is willing to + * wait to start receiving data, in the case that the content has not + * yet been uploaded. The default value is 20000 (20 seconds). The + * content repository can and should impose a maximum value for this + * parameter. The content repository may also choose to respond before + * the timeout. + */ + timeout_ms?: number; + /** + * Indicates to the server that it may return a 307 or 308 redirect response that points + * at the relevant media content. When not explicitly set to true the server must return + * the media content itself. + */ + allow_redirect?: boolean; + }; + }; + responses: { + /** The content that was previously uploaded. */ + 200: { + headers: {}; + schema: unknown; + }; + /** A redirect to the thumbnail of the requested content. */ + 307: never; + /** A redirect to the thumbnail of the requested content. */ + 308: never; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + /** The content is too large for the server to serve. */ + 502: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The content is not yet available. A [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + */ + 504: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * This will download content from the content repository (same as + * the previous endpoint) but replace the target file name with the one + * provided by the caller. + */ + getContentOverrideName: { + parameters: { + path: { + /** The server name from the `mxc://` URI (the authoritory component) */ + serverName: string; + /** The media ID from the `mxc://` URI (the path component) */ + mediaId: string; + /** A filename to give in the `Content-Disposition` header. */ + fileName: string; + }; + query: { + /** + * Indicates to the server that it should not attempt to fetch the media if it is deemed + * remote. This is to prevent routing loops where the server contacts itself. Defaults to + * true if not provided. + */ + allow_remote?: boolean; + /** + * The maximum number of milliseconds that the client is willing to + * wait to start receiving data, in the case that the content has not + * yet been uploaded. The default value is 20000 (20 seconds). The + * content repository can and should impose a maximum value for this + * parameter. The content repository may also choose to respond before + * the timeout. + */ + timeout_ms?: number; + /** + * Indicates to the server that it may return a 307 or 308 redirect response that points + * at the relevant media content. When not explicitly set to true the server must return + * the media content itself. + */ + allow_redirect?: boolean; + }; + }; + responses: { + /** The content that was previously uploaded. */ + 200: { + headers: {}; + schema: unknown; + }; + /** A redirect to the thumbnail of the requested content. */ + 307: never; + /** A redirect to the thumbnail of the requested content. */ + 308: never; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + /** The content is too large for the server to serve. */ + 502: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The content is not yet available. A [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + */ + 504: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + /** + * Get information about a URL for the client. Typically this is called when a + * client sees a URL in a message and wants to render a preview for the user. + * + * **Note:** + * Clients should consider avoiding this endpoint for URLs posted in encrypted + * rooms. Encrypted rooms often contain more sensitive information the users + * do not want to share with the homeserver, and this can mean that the URLs + * being shared should also not be shared with the homeserver. + */ + getUrlPreview: { + parameters: { + query: { + /** The URL to get a preview of. */ + url: string; + /** + * The preferred point in time to return a preview for. The server may + * return a newer version if it does not have the requested version + * available. + */ + ts?: number; + }; + }; + responses: { + /** + * The OpenGraph data for the URL, which may be empty. Some values are + * replaced with matrix equivalents if they are provided in the response. + * The differences from the OpenGraph protocol are described here. + */ + 200: { + schema: { + /** + * Format: int64 + * @description The byte-size of the image. Omitted if there is no image attached. + */ + "matrix:image:size"?: number; + /** + * Format: uri + * @description An [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris) to the image. Omitted if there is no image. + */ + "og:image"?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * Download a thumbnail of content from the content repository. + * See the [Thumbnails](https://spec.matrix.org/v1.7/client-server-api/#thumbnails) section for more information. + */ + getContentThumbnail: { + parameters: { + path: { + /** The server name from the `mxc://` URI (the authoritory component) */ + serverName: string; + /** The media ID from the `mxc://` URI (the path component) */ + mediaId: string; + }; + query: { + /** + * The *desired* width of the thumbnail. The actual thumbnail may be + * larger than the size specified. + */ + width: number; + /** + * The *desired* height of the thumbnail. The actual thumbnail may be + * larger than the size specified. + */ + height: number; + /** + * The desired resizing method. See the [Thumbnails](https://spec.matrix.org/v1.7/client-server-api/#thumbnails) + * section for more information. + */ + method?: "crop" | "scale"; + /** + * Indicates to the server that it should not attempt to fetch + * the media if it is deemed remote. This is to prevent routing loops + * where the server contacts itself. Defaults to true if not provided. + */ + allow_remote?: boolean; + /** + * The maximum number of milliseconds that the client is willing to + * wait to start receiving data, in the case that the content has not + * yet been uploaded. The default value is 20000 (20 seconds). The + * content repository can and should impose a maximum value for this + * parameter. The content repository may also choose to respond before + * the timeout. + */ + timeout_ms?: number; + /** + * Indicates to the server that it may return a 307 or 308 redirect response that points + * at the relevant media content. When not explicitly set to true the server must return + * the media content itself. + */ + allow_redirect?: boolean; + }; + }; + responses: { + /** A thumbnail of the requested content. */ + 200: { + headers: {}; + schema: unknown; + }; + /** A redirect to the thumbnail of the requested content. */ + 307: never; + /** A redirect to the thumbnail of the requested content. */ + 308: never; + /** + * The request does not make sense to the server, or the server cannot thumbnail + * the content. For example, the client requested non-integer dimensions or asked + * for negatively-sized images. + */ + 400: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The local content is too large for the server to thumbnail. */ + 413: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + /** The remote content is too large for the server to thumbnail. */ + 502: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The content is not yet available. A [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned with the `errcode` `M_NOT_YET_UPLOADED`. + */ + 504: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + }; + }; + uploadContent: { + parameters: { + header: { + /** The content type of the file being uploaded */ + "Content-Type"?: string; + }; + query: { + /** The name of the file being uploaded */ + filename?: string; + }; + body: { + /** The content to be uploaded. */ + content: string; + }; + }; + responses: { + /** The [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris) for the uploaded content. */ + 200: { + schema: { + /** + * Format: uri + * @description The [`mxc://` URI](https://spec.matrix.org/v1.7/client-server-api/#matrix-content-mxc-uris) to the uploaded content. + */ + content_uri: string; + }; + }; + /** + * The user does not have permission to upload the content. Some reasons for this error include: + * + * - The server does not permit the file type. + * - The user has reached a quota for uploaded content. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The uploaded content is too large for the server. */ + 413: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; + /** + * This endpoint permits uploading content to an `mxc://` URI that was created + * earlier via [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create). + */ + uploadContentToMXC: { + parameters: { + path: { + /** The server name from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the authoritory component). */ + serverName: string; + /** The media ID from the `mxc://` URI returned by `POST /_matrix/media/v1/create` (the path component). */ + mediaId: string; + }; + header: { + /** The content type of the file being uploaded */ + "Content-Type"?: string; + }; + query: { + /** The name of the file being uploaded */ + filename?: string; + }; + body: { + /** The content to be uploaded. */ + content: string; + }; + }; + responses: { + /** The upload was successful. */ + 200: { + schema: { [key: string]: unknown }; + }; + /** + * The user does not have permission to upload the content. Some reasons for this error include: + * + * - The server does not permit the file type. + * - The user has reached a quota for uploaded content. + * - The request comes from a different user than the one that called + * [POST /_matrix/media/v1/create](https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create). + * + * A [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned with the `errcode` `M_FORBIDDEN`. + */ + 403: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** + * The endpoint was called with a media ID that already has content. A + * [standard error response](https://spec.matrix.org/v1.7/client-server-api/#standard-error-response) + * will be returned with the `errcode` `M_CANNOT_OVERWRITE_MEDIA`. + */ + 409: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** The uploaded content is too large for the server. */ + 413: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + }; + }; + /** This request was rate-limited. */ + 429: { + schema: { + /** + * @description An error code. + * @example M_UNKNOWN + */ + errcode: string; + /** + * @description A human-readable error message. + * @example An unknown error occurred + */ + error?: string; + } & { + /** + * @description The M_LIMIT_EXCEEDED error code + * @example M_LIMIT_EXCEEDED + */ + errcode: string; + /** + * @description A human-readable error message. + * @example Too many requests + */ + error?: string; + /** + * @description The amount of time in milliseconds the client should wait + * before trying the request again. + * @example 2000 + */ + retry_after_ms?: number; + }; + }; + }; + }; +} + +export interface external {}