diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 27cbc389..06d161be 100644 --- a/content/client-server-api/_index.md +++ b/content/client-server-api/_index.md @@ -287,7 +287,7 @@ specify parameter values. The flow for this method is as follows: 1. Parse it as a URL. If it is not a URL, then `FAIL_ERROR`. 2. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the - `/_matrix/client/versions`\_ endpoint, ensuring that it does + [`/_matrix/client/versions`](/client-server-api/#get_matrixclientversions) endpoint, ensuring that it does not return an error, and parsing and validating that the data conforms with the expected response format. If any step in the validation fails, then `FAIL_ERROR`. Validation is @@ -1350,9 +1350,9 @@ The expected pattern for using lazy-loading is currently: The current endpoints which support lazy-loading room members are: -- `/sync`\_ -- `/rooms//messages`\_ -- `/rooms/{roomId}/context/{eventId}`\_ +- [`/sync`](/client-server-api/#get_matrixclientr0sync) +- [`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) +- [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientr0roomsroomidcontexteventid) ### API endpoints @@ -1486,13 +1486,13 @@ events. ### Syncing To read events, the intended flow of operation is for clients to first -call the `/sync`\_ API without a `since` parameter. This returns the +call the [`/sync`](/client-server-api/#get_matrixclientr0sync) API without a `since` parameter. This returns the most recent message events for each room, as well as the state of the room at the start of the returned timeline. The response also includes a `next_batch` field, which should be used as the value of the `since` parameter in the next call to `/sync`. Finally, the response includes, for each room, a `prev_batch` field, which can be passed as a `start` -parameter to the `/rooms//messages`\_ API to retrieve earlier +parameter to the [`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API to retrieve earlier messages. You can visualise the range of events being returned as: @@ -1529,7 +1529,7 @@ containing only the most recent message events. A state "delta" is also returned, summarising any state changes in the omitted part of the timeline. The client may therefore end up with "gaps" in its knowledge of the message timeline. The client can fill these gaps using the -`/rooms//messages`\_ API. This situation looks like this: +[`/rooms//messages`](/client-server-api/#get_matrixclientr0roomsroomidmessages) API. This situation looks like this: ``` | gap | @@ -1832,7 +1832,7 @@ A user can leave a room to stop receiving events for that room. A user must have been invited to or have joined the room before they are eligible to leave the room. Leaving a room to which the user has been invited rejects the invite. Once a user leaves a room, it will no longer -appear in the response to the `/sync`\_ API unless it is explicitly +appear in the response to the [`/sync`](/client-server-api/#get_matrixclientr0sync) API unless it is explicitly requested via a filter with the `include_leave` field set to `true`. Whether or not they actually joined the room, if the room is an @@ -1840,7 +1840,7 @@ Whether or not they actually joined the room, if the room is an re-join the room. A user can also forget a room which they have left. Rooms which have -been forgotten will never appear the response to the `/sync`\_ API, +been forgotten will never appear the response to the [`/sync`](/client-server-api/#get_matrixclientr0sync) API, until the user re-joins or is re-invited. A user may wish to force another user to leave a room. This can be done @@ -1861,7 +1861,7 @@ target user to leave the room and prevents them from re-joining the room. A banned user will not be treated as a joined user, and so will not be able to send or receive events in the room. In order to ban someone, the user performing the ban MUST have the required power level. -To ban a user, a request should be made to `/rooms//ban`\_ +To ban a user, a request should be made to [`/rooms//ban`](/client-server-api/#post_matrixclientr0roomsroomidban) with: ```json @@ -1883,7 +1883,7 @@ target member's state, by making a request to ``` A user must be explicitly unbanned with a request to -`/rooms//unban`\_ before they can re-join the room or be +[`/rooms//unban`](/client-server-api/#post_matrixclientr0roomsroomidunban) before they can re-join the room or be re-invited. {{% http-api spec="client-server" api="banning" %}} diff --git a/content/client-server-api/modules/dm.md b/content/client-server-api/modules/dm.md index c4f06bf3..59d09e3e 100644 --- a/content/client-server-api/modules/dm.md +++ b/content/client-server-api/modules/dm.md @@ -24,7 +24,7 @@ whether a chat is 'direct' to an invitee. #### Client behaviour To start a direct chat with another user, the inviting user's client -should set the `is_direct` flag to \_. The client should do this +should set the `is_direct` flag to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom). The client should do this whenever the flow the user has followed is one where their intention is to speak directly with another person, as opposed to bringing that person in to a shared room. For example, clicking on 'Start Chat' beside @@ -38,10 +38,10 @@ the flag altogether. Both the inviting client and the invitee's client should record the fact that the room is a direct chat by storing an `m.direct` event in the -account data using \_. +account data using [`/user//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). #### Server behaviour -When the `is_direct` flag is given to \_, the home server must set the +When the `is_direct` flag is given to [`/createRoom`](/client-server-api/#post_matrixclientr0createroom), the home server must set the `is_direct` flag in the invite member event for any users invited in the -\_ call. +[`/createRoom`](/client-server-api/#post_matrixclientr0createroom) call. diff --git a/content/client-server-api/modules/end_to_end_encryption.md b/content/client-server-api/modules/end_to_end_encryption.md index aea43eaa..13ecbdcc 100644 --- a/content/client-server-api/modules/end_to_end_encryption.md +++ b/content/client-server-api/modules/end_to_end_encryption.md @@ -113,13 +113,13 @@ key, and a number of signed Curve25519 one-time keys. ##### Uploading keys A device uploads the public parts of identity keys to their homeserver -as a signed JSON object, using the `/keys/upload`\_ API. The JSON object +as a signed JSON object, using the [`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API. The JSON object must include the public part of the device's Ed25519 key, and must be signed by that key, as described in [Signing JSON](/appendices/#signing-json). One-time keys are also uploaded to the homeserver using the -`/keys/upload`\_ API. +[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) API. Devices must store the private part of each key they upload. They can discard the private part of a one-time key when they receive a message @@ -134,12 +134,12 @@ too many private keys may discard keys starting with the oldest. Before Alice can send an encrypted message to Bob, she needs a list of each of his devices and the associated identity keys, so that she can establish an encryption session with each device. This list can be -obtained by calling `/keys/query`\_, passing Bob's user ID in the +obtained by calling [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in the `device_keys` parameter. From time to time, Bob may add new devices, and Alice will need to know this so that she can include his new devices for later encrypted -messages. A naive solution to this would be to call `/keys/query`\_ +messages. A naive solution to this would be to call [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) before sending each message -however, the number of users and devices may be large and this would be inefficient. @@ -157,23 +157,23 @@ process: list, and a separate flag to indicate that its list of Bob's devices is outdated. Both flags should be in storage which persists over client restarts. -2. It then makes a request to `/keys/query`\_, passing Bob's user ID in +2. It then makes a request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery), passing Bob's user ID in the `device_keys` parameter. When the request completes, it stores the resulting list of devices in persistent storage, and clears the 'outdated' flag. -3. During its normal processing of responses to \_, Alice's client - inspects the `changed` property of the `device_lists`\_ field. If it +3. During its normal processing of responses to [`/sync`](/client-server-api/#get_matrixclientr0sync), Alice's client + inspects the `changed` property of the [`device_lists`](/client-server-api/#extensions-to-sync-1) field. If it is tracking the device lists of any of the listed users, then it marks the device lists for those users outdated, and initiates - another request to `/keys/query`\_ for them. + another request to [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for them. 4. Periodically, Alice's client stores the `next_batch` field of the - result from \_ in persistent storage. If Alice later restarts her + result from [`/sync`](/client-server-api/#get_matrixclientr0sync) in persistent storage. If Alice later restarts her client, it can obtain a list of the users who have updated their - device list while it was offline by calling `/keys/changes`\_, + device list while it was offline by calling [`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges), passing the recorded `next_batch` field as the `from` parameter. If the client is tracking the device list of any of the users listed in the response, it marks them as outdated. It combines this list with - those already flagged as outdated, and initiates a `/keys/query`\_ + those already flagged as outdated, and initiates a [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) request for all of them. {{% boxes/warning %}} @@ -342,7 +342,7 @@ Example: A client wanting to set up a session with another device can claim a one-time key for that device. This is done by making a request to the -`/keys/claim`\_ API. +[`/keys/claim`](/client-server-api/#post_matrixclientr0keysclaim) API. A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public @@ -784,11 +784,11 @@ key, then Alice's device can trust Bob's master key, and she can sign it with her user-signing key. Users upload their cross-signing keys to the server using [POST -/\_matrix/client/r0/keys/device\_signing/upload](). When Alice uploads +/\_matrix/client/r0/keys/device\_signing/upload](/client-server-api/#post_matrixclientr0keysdevice_signingupload). When Alice uploads new cross-signing keys, her user ID will appear in the `changed` property of the `device_lists` field of the `/sync` of response of all users who share an encrypted room with her. When Bob sees Alice's user -ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query]() +ID in his `/sync`, he will call [POST /\_matrix/client/r0/keys/query](/client-server-api/#post_matrixclientr0keysquery) to retrieve Alice's device and cross-signing keys. If Alice has a device and wishes to send an encrypted message to Bob, @@ -959,8 +959,8 @@ be encrypted through the backup's `auth_data`; other clients can discover the backup by calling [GET /\_matrix/client/r0/room\_keys/version](#get_matrixclientr0room_keysversion). Keys are encrypted according to the backup's `auth_data` and added to the backup by calling [PUT -/\_matrix/client/r0/room\_keys/keys]() or one of its variants, and can -be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or +/\_matrix/client/r0/room\_keys/keys](#put_matrixclientr0room_keyskeys) or one of its variants, and can +be retrieved by calling [GET /\_matrix/client/r0/room\_keys/keys](#get_matrixclientr0room_keyskeys) or one of its variants. Keys can only be written to the most recently created version of the backup. Backups can also be deleted using [DELETE /\_matrix/client/r0/room\_keys/version/{version}](#delete_matrixclientr0room_keysversionversion), or individual keys @@ -1241,7 +1241,7 @@ correspond to the user who sent the event, `recipient` to the local user, and `recipient_keys` to the local ed25519 key. Clients must confirm that the `sender_key` and the `ed25519` field value -under the `keys` property match the keys returned by `/keys/query`\_ for +under the `keys` property match the keys returned by [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) for the given user, and must also verify the signature of the payload. Without this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm @@ -1373,17 +1373,17 @@ messages. ##### Extensions to /sync -This module adds an optional `device_lists` property to the \_ response, +This module adds an optional `device_lists` property to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response, as specified below. The server need only populate this property for an incremental `/sync` (i.e., one where the `since` parameter was -specified). The client is expected to use `/keys/query`\_ or -`/keys/changes`\_ for the equivalent functionality after an initial +specified). The client is expected to use [`/keys/query`](/client-server-api/#post_matrixclientr0keysquery) or +[`/keys/changes`](/client-server-api/#get_matrixclientr0keyschanges) for the equivalent functionality after an initial sync, as documented in [Tracking the device list for a user](#tracking-the-device-list-for-a-user). It also adds a `one_time_keys_count` property. Note the spelling difference with the `one_time_key_counts` property in the -`/keys/upload`\_ response. +[`/keys/upload`](/client-server-api/#post_matrixclientr0keysupload) response. | Parameter | Type | Description | |----------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------| diff --git a/content/client-server-api/modules/ignore_users.md b/content/client-server-api/modules/ignore_users.md index 51bb480d..b67f5976 100644 --- a/content/client-server-api/modules/ignore_users.md +++ b/content/client-server-api/modules/ignore_users.md @@ -17,7 +17,7 @@ and servers can implement the ignoring of users. To ignore a user, effectively blocking them, the client should add the target user to the `m.ignored_user_list` event in their account data -using \_. Once ignored, the client will no longer receive events sent by +using [`/user//account_data/`](/client-server-api/#put_matrixclientr0useruseridaccount_datatype). Once ignored, the client will no longer receive events sent by that user, with the exception of state events. The client should either hide previous content sent by the newly ignored user or perform a new `/sync` with no previous token. diff --git a/content/client-server-api/modules/send_to_device.md b/content/client-server-api/modules/send_to_device.md index c1778863..16ce3e46 100644 --- a/content/client-server-api/modules/send_to_device.md +++ b/content/client-server-api/modules/send_to_device.md @@ -13,26 +13,27 @@ client device. The primary motivation for this API is exchanging data that is meaningless or undesirable to persist in the room DAG - for example, one-time authentication tokens or key data. It is not intended for -conversational data, which should be sent using the normal \_ API for +conversational data, which should be sent using the normal [`/rooms//send`](/client-server-api/#put_matrixclientr0roomsroomidsendeventtypetxnid) API for consistency throughout Matrix. #### Client behaviour To send a message to other devices, a client should call -`/sendToDevice`\_. Only one message can be sent to each device per +[`/sendToDevice`](/client-server-api/#put_matrixclientr0sendtodeviceeventtypetxnid). Only one message can be sent to each device per transaction, and they must all have the same event type. The device ID in the request body can be set to `*` to request that the message be sent to all known devices. If there are send-to-device messages waiting for a client, they will be -returned by \_, as detailed in Extensions to /sync\_. Clients should +returned by [`/sync`](/client-server-api/#get_matrixclientr0sync), as detailed in [Extensions to /sync](/client-server-api/#extensions-to-sync). Clients should inspect the `type` of each returned event, and ignore any they do not understand. #### Server behaviour Servers should store pending messages for local users until they are -successfully delivered to the destination device. When a client calls \_ +successfully delivered to the destination device. When a client calls +[`/sync`](/client-server-api/#get_matrixclientr0sync) with an access token which corresponds to a device with pending messages, the server should list the pending messages, in order of arrival, in the response body. @@ -56,7 +57,7 @@ should be sent on to the remote servers via ##### Extensions to /sync -This module adds the following properties to the \_ response: +This module adds the following properties to the [`/sync`](/client-server-api/#get_matrixclientr0sync) response: | Parameter | Type | Description | |-----------|-----------|-----------------------------------------------------------------------------| diff --git a/content/client-server-api/modules/sso_login.md b/content/client-server-api/modules/sso_login.md index 18654b49..eb6a0bb9 100644 --- a/content/client-server-api/modules/sso_login.md +++ b/content/client-server-api/modules/sso_login.md @@ -43,12 +43,12 @@ endpoints which consume the ticket. An overview of the process is as follows: -1. The Matrix client calls `GET /login`\_ to find the supported login +1. The Matrix client calls [`GET /login`](/client-server-api/#get_matrixclientr0login) to find the supported login types, and the homeserver includes a flow with `"type": "m.login.sso"` in the response. 2. To initiate the `m.login.sso` login type, the Matrix client instructs the user's browser to navigate to the - `/login/sso/redirect`\_ endpoint on the user's homeserver. + [`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) endpoint on the user's homeserver. 3. The homeserver responds with an HTTP redirect to the SSO user interface, which the browser follows. 4. The authentication server and the homeserver interact to verify the @@ -57,7 +57,7 @@ An overview of the process is as follows: 5. The browser is directed to the `redirectUrl` provided by the client with a `loginToken` query parameter for the client to log in with. 6. The client exchanges the login token for an access token by calling - the `/login`\_ endpoint with a `type` of `m.login.token`. + the [`/login`](/client-server-api/#post_matrixclientr0login) endpoint with a `type` of `m.login.token`. For native applications, typically steps 1 to 4 are carried out by opening an embedded web view. @@ -100,7 +100,7 @@ otherwise the same. ##### Client behaviour The client starts the process by instructing the browser to navigate to -`/login/sso/redirect`\_ with an appropriate `redirectUrl`. Once +[`/login/sso/redirect`](/client-server-api/#get_matrixclientr0loginssoredirect) with an appropriate `redirectUrl`. Once authentication is successful, the browser will be redirected to that `redirectUrl`. @@ -178,7 +178,7 @@ The homeserver then proceeds as follows: registered as a new user. 3. The homeserver should generate a short-term login token. This is an opaque token, suitable for use with the `m.login.token` type of the - `/login`\_ API. The lifetime of this token SHOULD be limited to + [`/login`](/client-server-api/#post_matrixclientr0login) API. The lifetime of this token SHOULD be limited to around five seconds. 4. The homeserver adds a query parameter of `loginToken`, with the value of the generated login token, to the `redirectUrl` given in diff --git a/content/server-server-api.md b/content/server-server-api.md index 7e38e4b1..32db92d7 100644 --- a/content/server-server-api.md +++ b/content/server-server-api.md @@ -688,7 +688,7 @@ in practice will use just two. The first part of the handshake usually involves using the directory server to request the room ID and join candidates through the -`/query/directory`\_ API endpoint. In the case of a new user joining a +[`/query/directory`](/server-server-api/#get_matrixfederationv1querydirectory) API endpoint. In the case of a new user joining a room as a result of a received invite, the joining user's homeserver could optimise this step away by picking the origin server of that invite message as the join candidate. However, the joining server should