dandri/synapse
1
0
Fork 0
mirror of https://github.com/element-hq/synapse.git synced 2026-09-25 15:33:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

Replace manual notes in documentation with admonitions

Browse Source 
As they're generally prettier.

Requires https://github.com/element-hq/synapse/pull/19356
This commit is contained in:
Andrew Morgan
2026-01-07 16:31:55 +00:00
parent e660cf2cc4
commit d3045cd480
27 changed files with 171 additions and 138 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin_api/account_validity.md
+2 -1
View File
@@ -1,6 +1,7 @@
# Account validity API
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
This API allows a server administrator to manage the validity of an account. To
use it, you must enable the account validity feature (under
docs/admin_api/client_server_api_extensions.md
+3 -2
View File
@@ -22,8 +22,9 @@ To receive soft failed events in APIs like `/sync` and `/messages`, set `return_
to `true` in the admin client config. When `false`, the normal behaviour of these endpoints is to
exclude soft failed events.
**Note**: If the policy server flagged the event as spam and that caused soft failure, that will be indicated
in the event's `unsigned` content like so:
> [!NOTE]
> If the policy server flagged the event as spam and that caused soft failure, that will be indicated
> in the event's `unsigned` content like so:
```json
{
docs/admin_api/register_api.md
+2 -1
View File
@@ -1,6 +1,7 @@
# Shared-Secret Registration
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
This API allows for the creation of users in an administrative and
non-interactive way. This is generally used for bootstrapping a Synapse
docs/admin_api/rooms.md
+14 -9
View File
@@ -703,7 +703,8 @@ The parameters and response values have the same format as
## Version 2 (new version)
**Note**: This API is new, experimental and "subject to change".
> [!NOTE]
> This API is new, experimental and "subject to change".
This version works asynchronously, meaning you get the response from server immediately
while the server works on that task in background. You can then request the status of the action
@@ -770,7 +771,8 @@ The JSON body must not be empty. The body must be at least `{}`.
## Status of deleting rooms
**Note**: This API is new, experimental and "subject to change".
> [!NOTE]
> This API is new, experimental and "subject to change".
It is possible to query the status of the background task for deleting rooms.
The status can be queried up to 24 hours after completion of the task,
@@ -883,8 +885,9 @@ The following fields are returned in the JSON response body:
- `error` - A string that shows an error message if `status` is `failed`.
Otherwise this field is hidden.
- `shutdown_room` - An object containing information about the result of shutting down the room.
*Note:* The result is shown after removing the room members.
The delete process can still be running. Please pay attention to the `status`.
> [!NOTE]
> The result is shown after removing the room members.
> The delete process can still be running. Please pay attention to the `status`.
- `kicked_users` - An array of users (`user_id`) that were kicked.
- `failed_to_kick_users` - An array of users (`user_id`) that that were not kicked.
- `local_aliases` - An array of strings representing the local aliases that were
@@ -894,8 +897,9 @@ The following fields are returned in the JSON response body:
## Undoing room deletions
*Note*: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level,
the structure can and does change without notice.
> [!NOTE]
> This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level,
> the structure can and does change without notice.
First, it's important to understand that a room deletion is very destructive. Undoing a deletion is not as simple as pretending it
never happened - work has to be done to move forward instead of resetting the past. In fact, in some cases it might not be possible
@@ -978,9 +982,10 @@ A response as follows will be returned:
## Deleting forward extremities
**WARNING**: Please ensure you know what you're doing and have read
the related issue [#1760](https://github.com/matrix-org/synapse/issues/1760).
Under no situations should this API be executed as an automated maintenance task!
> [!WARNING]
> Please ensure you know what you're doing and have read
> the related issue [#1760](https://github.com/matrix-org/synapse/issues/1760).
> Under no situations should this API be executed as an automated maintenance task!
If a room has lots of forward extremities, the extra can be
deleted as follows:
docs/admin_api/statistics.md
+4 -3
View File
@@ -92,9 +92,10 @@ This does not include the size of any associated media associated with the room.
Returns an error on SQLite.
*Note:* This uses the planner statistics from PostgreSQL to do the estimates,
which means that the returned information can vary widely from reality. However,
it should be enough to get a rough idea of where database disk space is going.
> [!NOTE]
> This uses the planner statistics from PostgreSQL to do the estimates,
> which means that the returned information can vary widely from reality. However,
> it should be enough to get a rough idea of where database disk space is going.
The API is:
docs/admin_api/user_admin_api.md
+49 -37
View File
@@ -137,8 +137,9 @@ Body parameters:
- `address` - **string**, required. The third-party ID itself, e.g. `alice@example.com` for `email` or
`447470274584` (for a phone number with country code "44") and `19254857364` (for a phone number
with country code "1") for `msisdn`.
Note: If a threepid is removed from a user via this option, Synapse will also attempt to remove
that threepid from any identity servers it is aware has a binding for it.
> [!NOTE]
> If a threepid is removed from a user via this option, Synapse will also attempt to remove
> that threepid from any identity servers it is aware has a binding for it.
- `external_ids` - **array**, optional. Allow setting the identifier of the external identity
provider for SSO (Single sign-on). More details are in the configuration manual under the
sections [sso](../usage/configuration/config_documentation.md#sso) and [oidc_providers](../usage/configuration/config_documentation.md#oidc_providers).
@@ -151,15 +152,14 @@ Body parameters:
granting them access to the Admin API, among other things.
- `deactivated` - **bool**, optional. If unspecified, deactivation state will be left unchanged.
Note:
- For the password field there is no strict check of the necessity for its presence.
It is possible to have active users without a password, e.g. when authenticating with OIDC is configured.
You must check yourself whether a password is required when reactivating a user or not.
- It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`.
Users' passwords are wiped upon account deactivation, hence the need to set a new one here.
Note: a user cannot be erased with this API. For more details on
deactivating and erasing users see [Deactivate Account](#deactivate-account).
> [!NOTE]
> - For the password field there is no strict check of the necessity for its presence.
> It is possible to have active users without a password, e.g. when authenticating with OIDC is configured.
> You must check yourself whether a password is required when reactivating a user or not.
> - It is not possible to set a password if the config option `password_config.localdb_enabled` is set `false`.
> Users' passwords are wiped upon account deactivation, hence the need to set a new one here.
> - A user cannot be erased with this API. For more details on
> deactivating and erasing users see [Deactivate Account](#deactivate-account).
- `locked` - **bool**, optional. If unspecified, locked state will be left unchanged.
- `user_type` - **string** or null, optional. If not provided, the user type will be
not be changed. If `null` is given, the user type will be cleared.
@@ -259,12 +259,15 @@ The following parameters should be set in the URL:
Can be provided multiple times. Possible values are `bot`, `support` or "empty string".
"empty string" here means to exclude users without a type.
- `locked` - string representing a bool - Is optional and if `true` will **include** locked users.
Defaults to `false` to exclude locked users. Note: Introduced in v1.93.
Defaults to `false` to exclude locked users.
> [!NOTE]
> Introduced in v1.93.
Caution. The database only has indexes on the columns `name` and `creation_ts`.
This means that if a different sort order is used (`is_guest`, `admin`,
`user_type`, `deactivated`, `shadow_banned`, `avatar_url` or `displayname`),
this can cause a large load on the database, especially for large environments.
> [!CAUTION]
> The database only has indexes on the columns `name` and `creation_ts`.
> This means that if a different sort order is used (`is_guest`, `admin`,
> `user_type`, `deactivated`, `shadow_banned`, `avatar_url` or `displayname`),
> this can cause a large load on the database, especially for large environments.
**Response**
@@ -285,7 +288,9 @@ The following fields are returned in the JSON response body:
- `avatar_url` - string - The user's avatar URL if they have set one.
- `creation_ts` - integer - The user's creation timestamp in ms.
- `last_seen_ts` - integer - The user's last activity timestamp in ms.
- `locked` - bool - Status if that user has been marked as locked. Note: Introduced in v1.93.
- `locked` - bool - Status if that user has been marked as locked.
> [!NOTE]
> Introduced in v1.93.
- `next_token`: string representing a positive integer - Indication for pagination. See above.
- `total` - integer - Total number of media.
@@ -443,7 +448,8 @@ To unsuspend a user, use the same endpoint with a body of:
## Reset password
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
Changes the password of another user. This will automatically log the user out of all their devices.
@@ -468,7 +474,8 @@ The parameter `logout_devices` is optional and defaults to `true`.
## Get whether a user is a server administrator or not
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
The api is:
@@ -487,7 +494,8 @@ A response body like the following is returned:
## Change whether a user is a server administrator or not
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
Note that you cannot demote yourself.
@@ -614,8 +622,9 @@ The following should be set as query parameters in the URL:
invites sent at or after the provided timestamp will be returned.
This works by comparing the provided timestamp to the `received_ts`
column in the `events` table.
Note: https://currentmillis.com/ is a useful tool for converting dates
into timestamps and vice versa.
> [!NOTE]
> https://currentmillis.com/ is a useful tool for converting dates
> into timestamps and vice versa.
A response body like the following is returned:
@@ -648,8 +657,9 @@ The following should be set as query parameters in the URL:
invites sent at or after the provided timestamp will be returned.
This works by comparing the provided timestamp to the `received_ts`
column in the `events` table.
Note: https://currentmillis.com/ is a useful tool for converting dates
into timestamps and vice versa.
> [!NOTE]
> https://currentmillis.com/ is a useful tool for converting dates
> into timestamps and vice versa.
A response body like the following is returned:
@@ -836,11 +846,12 @@ The following parameters should be set in the URL:
If neither `order_by` nor `dir` is set, the default order is newest media on top
(corresponds to `order_by` = `created_ts` and `dir` = `b`).
Caution. The database only has indexes on the columns `media_id`,
`user_id` and `created_ts`. This means that if a different sort order is used
(`upload_name`, `last_access_ts`, `media_length`, `media_type`,
`quarantined_by` or `safe_from_quarantine`), this can cause a large load on the
database, especially for large environments.
> [!CAUTION]
> The database only has indexes on the columns `media_id`,
> `user_id` and `created_ts`. This means that if a different sort order is used
> (`upload_name`, `last_access_ts`, `media_length`, `media_type`,
> `quarantined_by` or `safe_from_quarantine`), this can cause a large load on the
> database, especially for large environments.
**Response**
@@ -897,8 +908,9 @@ The following fields are returned in the JSON response body:
* `deleted_media`: an array of strings - List of deleted `media_id`
* `total`: integer - Total number of deleted `media_id`
**Note**: There is no `next_token`. This is not useful for deleting media, because
after deleting media the remaining media have a new order.
> [!NOTE]
> There is no `next_token`. This is not useful for deleting media, because
> after deleting media the remaining media have a new order.
**Parameters**
@@ -909,7 +921,8 @@ delete largest/smallest or newest/oldest files first.
## Login as a user
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
> [!NOTE]
> This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
Get an access token that can be used to authenticate as that user. Useful for
when admins wish to do actions on behalf of a user.
@@ -940,9 +953,10 @@ tell they have been logged in as.
To expire the token call the standard `/logout` API with the token.
Note: The token will expire if the *admin* user calls `/logout/all` from any
of their devices, but the token will *not* expire if the target user does the
same.
> [!NOTE]
> The token will expire if the *admin* user calls `/logout/all` from any
> of their devices, but the token will *not* expire if the target user does the
> same.
## Allow replacing master cross-signing key without User-Interactive Auth
@@ -1598,5 +1612,3 @@ The following fields are returned in the JSON response body:
the corresponding error that caused the redaction to fail
_Added in Synapse 1.116.0._