diff --git a/docs/admin_api/event_reports.md b/docs/admin_api/event_reports.md
index 83f7dc37f4..9075e92882 100644
--- a/docs/admin_api/event_reports.md
+++ b/docs/admin_api/event_reports.md
@@ -60,10 +60,11 @@ paginate through.
anything other than the return value of `next_token` from a previous call. Defaults to `0`.
* `dir`: string - Direction of event report order. Whether to fetch the most recent
first (`b`) or the oldest first (`f`). Defaults to `b`.
-* `user_id`: string - Is optional and filters to only return users with user IDs that
- contain this value. This is the user who reported the event and wrote the reason.
-* `room_id`: string - Is optional and filters to only return rooms with room IDs that
- contain this value.
+* `user_id`: optional string - Filter by the user ID of the reporter. This is the user who reported the event
+ and wrote the reason.
+* `room_id`: optional string - Filter by room id.
+* `event_sender_user_id`: optional string - Filter by the sender of the reported event. This is the user who
+ the report was made against.
**Response**
diff --git a/docs/admin_api/experimental_features.md b/docs/admin_api/experimental_features.md
index ef1b58c9ba..e32728e56d 100644
--- a/docs/admin_api/experimental_features.md
+++ b/docs/admin_api/experimental_features.md
@@ -5,6 +5,7 @@ basis. The currently supported features are:
- [MSC3881](https://github.com/matrix-org/matrix-spec-proposals/pull/3881): enable remotely toggling push notifications
for another client
- [MSC3575](https://github.com/matrix-org/matrix-spec-proposals/pull/3575): enable experimental sliding sync support
+- [MSC4222](https://github.com/matrix-org/matrix-spec-proposals/pull/4222): adding `state_after` to sync v2
To use it, you will need to authenticate by providing an `access_token`
for a server admin: see [Admin API](../usage/administration/admin_api/).
diff --git a/docs/admin_api/media_admin_api.md b/docs/admin_api/media_admin_api.md
index 30833f3109..1177711c1e 100644
--- a/docs/admin_api/media_admin_api.md
+++ b/docs/admin_api/media_admin_api.md
@@ -46,6 +46,14 @@ to any local media, and any locally-cached copies of remote media.
The media file itself (and any thumbnails) is not deleted from the server.
+Since Synapse 1.128.0, hashes of uploaded media are tracked. If this media
+is quarantined, Synapse will:
+
+ - Quarantine any media with a matching hash that has already been uploaded.
+ - Quarantine any future media.
+ - Quarantine any existing cached remote media.
+ - Quarantine any future remote media.
+
## Quarantining media by ID
This API quarantines a single piece of local or remote media.
diff --git a/docs/admin_api/rooms.md b/docs/admin_api/rooms.md
index 8e3a367e90..bdda9b47ad 100644
--- a/docs/admin_api/rooms.md
+++ b/docs/admin_api/rooms.md
@@ -385,6 +385,13 @@ The API is:
GET /_synapse/admin/v1/rooms/<room_id>/state
```
+**Parameters**
+
+The following query parameter is available:
+
+* `type` - The type of room state event to filter by, eg "m.room.create". If provided, only state events
+ of this type will be returned (regardless of their `state_key` value).
+
A response body like the following is returned:
```json
@@ -787,6 +794,7 @@ A response body like the following is returned:
"results": [
{
"delete_id": "delete_id1",
+ "room_id": "!roomid:example.com",
"status": "failed",
"error": "error message",
"shutdown_room": {
@@ -797,6 +805,7 @@ A response body like the following is returned:
}
}, {
"delete_id": "delete_id2",
+ "room_id": "!roomid:example.com",
"status": "purging",
"shutdown_room": {
"kicked_users": [
@@ -835,6 +844,8 @@ A response body like the following is returned:
```json
{
"status": "purging",
+ "delete_id": "bHkCNQpHqOaFhPtK",
+ "room_id": "!roomid:example.com",
"shutdown_room": {
"kicked_users": [
"@foobar:example.com"
@@ -862,7 +873,8 @@ The following fields are returned in the JSON response body:
- `results` - An array of objects, each containing information about one task.
This field is omitted from the result when you query by `delete_id`.
Task objects contain the following fields:
- - `delete_id` - The ID for this purge if you query by `room_id`.
+ - `delete_id` - The ID for this purge
+ - `room_id` - The ID of the room being deleted
- `status` - The status will be one of:
- `shutting_down` - The process is removing users from the room.
- `purging` - The process is purging the room and event data from database.
diff --git a/docs/admin_api/scheduled_tasks.md b/docs/admin_api/scheduled_tasks.md
new file mode 100644
index 0000000000..b80da5083c
--- /dev/null
+++ b/docs/admin_api/scheduled_tasks.md
@@ -0,0 +1,54 @@
+# Show scheduled tasks
+
+This API returns information about scheduled tasks.
+
+To use it, you will need to authenticate by providing an `access_token`
+for a server admin: see [Admin API](../usage/administration/admin_api/).
+
+The api is:
+```
+GET /_synapse/admin/v1/scheduled_tasks
+```
+
+It returns a JSON body like the following:
+
+```json
+{
+ "scheduled_tasks": [
+ {
+ "id": "GSA124oegf1",
+ "action": "shutdown_room",
+ "status": "complete",
+ "timestamp_ms": 23423523,
+ "resource_id": "!roomid",
+ "result": "some result",
+ "error": null
+ }
+ ]
+}
+```
+
+**Query parameters:**
+
+* `action_name`: string - Is optional. Returns only the scheduled tasks with the given action name.
+* `resource_id`: string - Is optional. Returns only the scheduled tasks with the given resource id.
+* `status`: string - Is optional. Returns only the scheduled tasks matching the given status, one of
+ - "scheduled" - Task is scheduled but not active
+ - "active" - Task is active and probably running, and if not will be run on next scheduler loop run
+ - "complete" - Task has completed successfully
+ - "failed" - Task is over and either returned a failed status, or had an exception
+
+* `max_timestamp`: int - Is optional. Returns only the scheduled tasks with a timestamp inferior to the specified one.
+
+**Response**
+
+The following fields are returned in the JSON response body along with a `200` HTTP status code:
+
+* `id`: string - ID of scheduled task.
+* `action`: string - The name of the scheduled task's action.
+* `status`: string - The status of the scheduled task.
+* `timestamp_ms`: integer - The timestamp (in milliseconds since the unix epoch) of the given task - If the status is "scheduled" then this represents when it should be launched.
+ Otherwise it represents the last time this task got a change of state.
+* `resource_id`: Optional string - The resource id of the scheduled task, if it possesses one
+* `result`: Optional Json - Any result of the scheduled task, if given
+* `error`: Optional string - If the task has the status "failed", the error associated with this failure
diff --git a/docs/admin_api/user_admin_api.md b/docs/admin_api/user_admin_api.md
index 2281385830..d526072d2f 100644
--- a/docs/admin_api/user_admin_api.md
+++ b/docs/admin_api/user_admin_api.md
@@ -19,20 +19,6 @@ It returns a JSON body like the following:
{
"name": "@user:example.com",
"displayname": "User", // can be null if not set
- "threepids": [
- {
- "medium": "email",
- "address": "<user_mail_1>",
- "added_at": 1586458409743,
- "validated_at": 1586458409743
- },
- {
- "medium": "email",
- "address": "<user_mail_2>",
- "added_at": 1586458409743,
- "validated_at": 1586458409743
- }
- ],
"avatar_url": "<avatar_url>", // can be null if not set
"is_guest": 0,
"admin": 0,
@@ -40,6 +26,7 @@ It returns a JSON body like the following:
"erased": false,
"shadow_banned": 0,
"creation_ts": 1560432506,
+ "last_seen_ts": 1732919539393,
"appservice_id": null,
"consent_server_notice_sent": null,
"consent_version": null,
@@ -55,7 +42,8 @@ It returns a JSON body like the following:
}
],
"user_type": null,
- "locked": false
+ "locked": false,
+ "suspended": false
}
```
@@ -82,16 +70,6 @@ with a body of:
"logout_devices": false,
"displayname": "Alice Marigold",
"avatar_url": "mxc://example.com/abcde12345",
- "threepids": [
- {
- "medium": "email",
- "address": "alice@example.com"
- },
- {
- "medium": "email",
- "address": "alice@domain.org"
- }
- ],
"external_ids": [
{
"auth_provider": "example",
@@ -128,15 +106,6 @@ Body parameters:
- `avatar_url` - **string**, optional. Must be a
[MXC URI](https://matrix.org/docs/spec/client_server/r0.6.0#matrix-content-mxc-uris).
If set to an empty string (`""`), the user's avatar is removed.
-- `threepids` - **array**, optional. If provided, the user's third-party IDs (email, msisdn) are
- entirely replaced with the given list. Each item in the array is an object with the following
- fields:
- - `medium` - **string**, required. The type of third-party ID, either `email` or `msisdn` (phone number).
- - `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.
- `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).
@@ -161,7 +130,8 @@ Body parameters:
- `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.
- Other allowed options are: `bot` and `support`.
+ Other allowed options are: `bot` and `support` and any extra values defined in the homserver
+ [configuration](../usage/configuration/config_documentation.md#user_types).
## List Accounts
### List Accounts (V2)
@@ -412,6 +382,32 @@ The following actions are **NOT** performed. The list may be incomplete.
- Remove from monthly active users
- Remove user's consent information (consent version and timestamp)
+## Suspend/Unsuspend Account
+
+This API allows an admin to suspend/unsuspend an account. While an account is suspended, the user is
+prohibited from sending invites, joining or knocking on rooms, sending messages, changing profile data, and redacting messages other than their own.
+
+The api is:
+
+```
+PUT /_synapse/admin/v1/suspend/<user_id>
+```
+
+with a body of:
+
+```json
+{
+ "suspend": true
+}
+```
+
+To unsuspend a user, use the same endpoint with a body of:
+```json
+{
+ "suspend": false
+}
+```
+
## Reset password
**Note:** This API is disabled when MSC3861 is enabled. [See #15582](https://github.com/matrix-org/synapse/pull/15582)
@@ -476,9 +472,9 @@ with a body of:
}
```
-## List room memberships of a user
+## List joined rooms of a user
-Gets a list of all `room_id` that a specific `user_id` is member.
+Gets a list of all `room_id` that a specific `user_id` is joined to and is a member of (participating in).
The API is:
@@ -515,6 +511,73 @@ The following fields are returned in the JSON response body:
- `joined_rooms` - An array of `room_id`.
- `total` - Number of rooms.
+## Get the number of invites sent by the user
+
+Fetches the number of invites sent by the provided user ID across all rooms
+after the given timestamp.
+
+```
+GET /_synapse/admin/v1/users/$user_id/sent_invite_count
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `user_id`: fully qualified: for example, `@user:server.com`
+
+The following should be set as query parameters in the URL:
+
+* `from_ts`: int, required. A timestamp in ms from the unix epoch. Only
+ 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.
+
+A response body like the following is returned:
+
+```json
+{
+ "invite_count": 30
+}
+```
+
+_Added in Synapse 1.122.0_
+
+## Get the cumulative number of rooms a user has joined after a given timestamp
+
+Fetches the number of rooms that the user joined after the given timestamp, even
+if they have subsequently left/been banned from those rooms.
+
+```
+GET /_synapse/admin/v1/users/$<user_id/cumulative_joined_room_count
+```
+
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `user_id`: fully qualified: for example, `@user:server.com`
+
+The following should be set as query parameters in the URL:
+
+* `from_ts`: int, required. A timestamp in ms from the unix epoch. Only
+ 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.
+
+A response body like the following is returned:
+
+```json
+{
+ "cumulative_joined_room_count": 30
+}
+```
+_Added in Synapse 1.122.0_
+
## Account Data
Gets information about account data for a specific `user_id`.
@@ -859,7 +922,8 @@ A response body like the following is returned:
"last_seen_ip": "1.2.3.4",
"last_seen_user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0",
"last_seen_ts": 1474491775024,
- "user_id": "<user_id>"
+ "user_id": "<user_id>",
+ "dehydrated": false
},
{
"device_id": "AUIECTSRND",
@@ -867,7 +931,8 @@ A response body like the following is returned:
"last_seen_ip": "1.2.3.5",
"last_seen_user_agent": "Mozilla/5.0 (X11; Linux x86_64; rv:103.0) Gecko/20100101 Firefox/103.0",
"last_seen_ts": 1474491775025,
- "user_id": "<user_id>"
+ "user_id": "<user_id>",
+ "dehydrated": false
}
],
"total": 2
@@ -897,6 +962,7 @@ The following fields are returned in the JSON response body:
- `last_seen_ts` - 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).
- `user_id` - Owner of device.
+ - `dehydrated` - Whether the device is a dehydrated device.
- `total` - Total number of user's devices.
@@ -1306,7 +1372,7 @@ When a user matched the given ID for the given provider, an HTTP code `200` with
The following parameters should be set in the URL:
- `provider` - The ID of the authentication provider, as advertised by the [`GET /_matrix/client/v3/login`](https://spec.matrix.org/latest/client-server-api/#post_matrixclientv3login) API in the `m.login.sso` authentication method.
-- `external_id` - The user ID from the authentication provider. Usually corresponds to the `sub` claim for OIDC providers, or to the `uid` attestation for SAML2 providers.
+- `external_id` - The user ID from the authentication provider. Usually corresponds to the `sub` claim for OIDC providers.
The `external_id` may have characters that are not URL-safe (typically `/`, `:` or `@`), so it is advised to URL-encode those parameters.
@@ -1324,19 +1390,28 @@ Returns a `404` HTTP status code if no user was found, with a response body like
_Added in Synapse 1.68.0._
-## Find a user based on their Third Party ID (ThreePID or 3PID)
+## Redact all the events of a user
-The API is:
+This endpoint allows an admin to redact the events of a given user. There are no restrictions on redactions for a
+local user. By default, we puppet the user who sent the message to redact it themselves. Redactions for non-local users are issued using the admin user, and will fail in rooms where the admin user is not admin/does not have the specified power level to issue redactions.
+The API is
```
-GET /_synapse/admin/v1/threepid/$medium/users/$address
+POST /_synapse/admin/v1/user/$user_id/redact
+
+{
+ "rooms": ["!roomid1", "!roomid2"]
+}
```
+If an empty list is provided as the key for `rooms`, all events in all the rooms the user is member of will be redacted,
+otherwise all the events in the rooms provided in the request will be redacted.
-When a user matched the given address for the given medium, an HTTP code `200` with a response body like the following is returned:
+The API starts redaction process running, and returns immediately with a JSON body with
+a redact id which can be used to query the status of the redaction process:
```json
{
- "user_id": "@hello:example.org"
+ "redact_id": "<opaque id>"
}
```
@@ -1344,20 +1419,57 @@ When a user matched the given address for the given medium, an HTTP code `200` w
The following parameters should be set in the URL:
-- `medium` - Kind of third-party ID, either `email` or `msisdn`.
-- `address` - Value of the third-party ID.
+- `user_id` - The fully qualified MXID of the user: for example, `@user:server.com`.
-The `address` may have characters that are not URL-safe, so it is advised to URL-encode those parameters.
+The following JSON body parameter must be provided:
-**Errors**
+- `rooms` - A list of rooms to redact the user's events in. If an empty list is provided all events in all rooms
+ the user is a member of will be redacted
-Returns a `404` HTTP status code if no user was found, with a response body like this:
+The following JSON body parameters are optional:
-```json
+- `reason` - Reason the redaction is being requested, ie "spam", "abuse", etc. This will be included in each redaction event, and be visible to users.
+- `limit` - a limit on the number of the user's events to search for ones that can be redacted (events are redacted newest to oldest) in each room, defaults to 1000 if not provided
+
+_Added in Synapse 1.116.0._
+
+
+## Check the status of a redaction process
+
+It is possible to query the status of the background task for redacting a user's events.
+The status can be queried up to 24 hours after completion of the task,
+or until Synapse is restarted (whichever happens first).
+
+The API is:
+
+```
+GET /_synapse/admin/v1/user/redact_status/$redact_id
+```
+
+A response body like the following is returned:
+
+```
{
- "errcode":"M_NOT_FOUND",
- "error":"User not found"
+ "status": "active",
+ "failed_redactions": [],
}
```
-_Added in Synapse 1.72.0._
+**Parameters**
+
+The following parameters should be set in the URL:
+
+* `redact_id` - string - The ID for this redaction process, provided when the redaction was requested.
+
+
+**Response**
+
+The following fields are returned in the JSON response body:
+
+- `status` - string - one of scheduled/active/completed/failed, indicating the status of the redaction job
+- `failed_redactions` - dictionary - the keys of the dict are event ids the process was unable to redact, if any, and the values are
+ the corresponding error that caused the redaction to fail
+
+_Added in Synapse 1.116.0._
+
+
|
