Add documentation for new admin API to remove a local user from a space
2 files changed, 47 insertions, 0 deletions
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index cdedf8bccc..e71df89797 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -60,6 +60,7 @@
- [Registration Tokens](usage/administration/admin_api/registration_tokens.md)
- [Manipulate Room Membership](admin_api/room_membership.md)
- [Rooms](admin_api/rooms.md)
+ - [Spaces](usage/administration/admin_api/spaces.md)
- [Server Notices](admin_api/server_notices.md)
- [Statistics](admin_api/statistics.md)
- [Users](admin_api/user_admin_api.md)
diff --git a/docs/usage/administration/admin_api/spaces.md b/docs/usage/administration/admin_api/spaces.md
new file mode 100644
index 0000000000..ac91749407
--- /dev/null
+++ b/docs/usage/administration/admin_api/spaces.md
@@ -0,0 +1,46 @@
+# Spaces API
+
+This API allows a server administrator to manage spaces.
+
+## Remove local user
+
+This API forces a local user to leave all non-public rooms in a space.
+
+The space itself is always left, regardless of whether it is public.
+
+May succeed partially if the user fails to leave some rooms.
+
+The API is:
+
+```
+DELETE /_synapse/admin/v1/rooms/<room_id>/hierarchy/members/<user_id>
+```
+
+Returning:
+
+```json
+{
+ "left": ["!room1:example.net", "!room2:example.net", ...],
+ "failed": {
+ "!room3:example.net": [
+ "Could not explore space or room fully."
+ ],
+ "!room4:example.net": [
+ "Failed to leave room."
+ ],
+ ...
+ }
+}
+```
+
+`left`: A list of rooms that the user has been made to leave.
+
+`failed`: A dictionary with entries for rooms that could not be fully
+processed. The values of the dictionary are lists of failure reasons.
+Rooms may appear here if:
+ * The user failed to leave them for any reason.
+ * The room is a space that the local homeserver is not in, and so
+ its full list of child rooms could not be determined.
+ * The room is inaccessible to the local homeserver, and it is not
+ known whether the room is a subspace containing further rooms.
+ * Some combination of the above.
|
