Add Admin API endpoints to list, fetch and delete room reports

changelog.d/19648.feature

@@ -0,0 +1 @@
+Add [Admin API](https://matrix-org.github.io/synapse/develop/usage/administration/admin_api/index.html) endpoints to list, fetch and delete room reports.

docs/SUMMARY.md

@@ -63,6 +63,7 @@
       - [Background Updates](usage/administration/admin_api/background_updates.md)
       - [Fetch Event](admin_api/fetch_event.md)
       - [Event Reports](admin_api/event_reports.md)
+      - [Room Reports](admin_api/room_reports.md)
       - [Experimental Features](admin_api/experimental_features.md)
       - [Media](admin_api/media_admin_api.md)
       - [Purge History](admin_api/purge_history_api.md)

docs/admin_api/room_reports.md

@@ -0,0 +1,137 @@
+# Show reported rooms
+
+This API returns information about reported rooms.
+
+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/room_reports
+```
+
+It returns a JSON body like the following:
+
+```json
+{
+    "room_reports": [
+        {
+            "id": 2,
+            "received_ts": 1570897107409,
+            "room_id": "!ERAgBpSOcCCuTJqQPk:matrix.org",
+            "user_id": "@foo:matrix.org",
+            "reason": "This room contains spam",
+            "canonical_alias": "#alias1:matrix.org",
+            "name": "Matrix chat",
+            "topic": "Discussions about Matrix"
+        },
+        {
+            "id": 3,
+            "received_ts": 1598889612059,
+            "room_id": "!eGvUQuTCkHGVwNMOjv:matrix.org",
+            "user_id": "@bar:matrix.org",
+            "reason": "Inappropriate content",
+            "canonical_alias": null,
+            "name": "Nefarious room",
+            "topic": null
+        }
+    ],
+    "next_batch": 2,
+    "total": 4
+}
+```
+
+Note: Reports for deleted or purged rooms are not returned. The endpoint returns reports in descending
+chronological order.
+
+To paginate, check for `next_batch` and if present, call the endpoint again with `from`
+set to the value of `next_batch`. This will return a new page.
+
+If the endpoint does not return a `next_batch` then there are no more reports to
+paginate through.
+
+**URL query parameters:**
+
+* `limit`: positive integer - Optional. Used for pagination, denoting the maximum number
+  of items to return in this call. Defaults to `100` if not provided.
+* `from`: positive integer - Optional. Used for pagination, denoting the unix ms timestamp to return results
+   from in descending order. Defaults to the current time. 
+* `user_id`: string - Optional. Filter by the user ID of the reporter. This is the user who
+  reported the room.
+* `room_id`: string - Optional. Filter by room id.
+
+**Response**
+
+The following fields are returned in the JSON response body:
+
+* `id`: integer - ID of room report.
+* `received_ts`: integer - The timestamp (in milliseconds since the unix epoch) when this
+  report was sent.
+* `room_id`: string - The ID of the reported room.
+* `user_id`: string - This is the user who reported the room.
+* `reason`: string - Comment made by the `user_id` in this report indicating why the room
+  was reported. May be blank or `null`.
+* `canonical_alias`: string - The canonical alias of the room. `null` if the room does not
+  have a canonical alias set.
+* `name`: string - The name of the room.
+* `topic`: string - The topic of the room. `null` if the room does not have a topic set.
+* `next_batch`: integer - Indication for pagination. See above.
+* `total`: integer - Total number of room reports related to the query
+  (`user_id` and `room_id`).
+
+# Show details of a specific room report
+
+This API returns information about a specific room report.
+
+The api is:
+```
+GET /_synapse/admin/v1/room_reports/<report_id>
+```
+
+It returns a JSON body like the following:
+
+```json
+{
+    "id": 2,
+    "received_ts": 1570897107409,
+    "room_id": "!ERAgBpSOcCCuTJqQPk:matrix.org",
+    "user_id": "@foo:matrix.org",
+    "reason": "This room contains spam",
+    "canonical_alias": "#alias1:matrix.org",
+    "name": "Matrix HQ",
+    "topic": "Discussions about Matrix"
+}
+```
+
+**URL parameters:**
+
+* `report_id`: string - The ID of the room report.
+
+**Response**
+
+The following fields are returned in the JSON response body:
+
+* `id`: integer - ID of room report.
+* `received_ts`: integer - The timestamp (in milliseconds since the unix epoch) when this
+  report was sent.
+* `room_id`: string - The ID of the reported room.
+* `name`: string - The name of the room.
+* `user_id`: string - This is the user who reported the room.
+* `reason`: string - Comment made by the `user_id` in this report. May be blank.
+* `canonical_alias`: string - The canonical alias of the room. `null` if the room does not
+  have a canonical alias set.
+* `topic`: string - The topic of the room. `null` if the room does not have a topic set.
+
+# Delete a specific room report
+
+This API deletes a specific room report. If the request is successful, the response body
+will be an empty JSON object.
+
+The api is:
+```
+DELETE /_synapse/admin/v1/room_reports/<report_id>
+```
+
+**URL parameters:**
+
+* `report_id`: string - The ID of the room report to delete.

synapse/rest/admin/__init__.py

@@ -73,6 +73,10 @@
     NewRegistrationTokenRestServlet,
     RegistrationTokenRestServlet,
 )
+from synapse.rest.admin.room_reports import (
+    RoomReportDetailRestServlet,
+    RoomReportsRestServlet,
+)
 from synapse.rest.admin.rooms import (
     AdminRoomHierarchy,
     BlockRoomRestServlet,
@@ -316,6 +320,8 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
     LargestRoomsStatistics(hs).register(http_server)
     EventReportDetailRestServlet(hs).register(http_server)
     EventReportsRestServlet(hs).register(http_server)
+    RoomReportDetailRestServlet(hs).register(http_server)
+    RoomReportsRestServlet(hs).register(http_server)
     UserReportsRestServlet(hs).register(http_server)
     UserReportDetailRestServlet(hs).register(http_server)
     AccountDataRestServlet(hs).register(http_server)

synapse/rest/admin/room_reports.py

@@ -0,0 +1,165 @@
+#
+# This file is licensed under the Affero General Public License (AGPL) version 3.
+#
+# Copyright (C) 2026 Element Creations Ltd
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# See the GNU Affero General Public License for more details:
+# <https://www.gnu.org/licenses/agpl-3.0.html>.
+#
+
+
+import logging
+from http import HTTPStatus
+from typing import TYPE_CHECKING
+
+from synapse.api.errors import Codes, NotFoundError, SynapseError
+from synapse.http.servlet import RestServlet, parse_integer, parse_string
+from synapse.http.site import SynapseRequest
+from synapse.rest.admin._base import admin_patterns, assert_requester_is_admin
+from synapse.types import JsonDict
+
+if TYPE_CHECKING:
+    from synapse.server import HomeServer
+
+logger = logging.getLogger(__name__)
+
+
+class RoomReportsRestServlet(RestServlet):
+    """
+    List all existing rooms that have been reported to the homeserver. Results are returned
+    in a dictionary containing report information. Supports pagination. Does not return results
+    for deleted/purged rooms.
+    The requester must have administrator access in Synapse.
+
+    GET /_synapse/admin/v1/room_reports
+    returns:
+        200 OK with list of reports if success otherwise an error.
+
+    Args:
+        The parameters `from` and `limit` are required only for pagination.
+        By default, a `limit` of 100 is used, and the `from` parameter defaults to the current time.
+        The `room_id` query parameter filters by room id.
+        The `user_id` query parameter filters by the user ID of the reporter of the room.
+    Returns:
+        A list of reported rooms and an integer representing the total number of
+        reported rooms that exist given this query
+    """
+
+    PATTERNS = admin_patterns("/room_reports$")
+
+    def __init__(self, hs: "HomeServer"):
+        self._auth = hs.get_auth()
+        self._store = hs.get_datastores().main
+        self._clock = hs.get_clock()
+
+    async def on_GET(self, request: SynapseRequest) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        now = int(self._clock.time_msec()) + 1
+        start = parse_integer(request, "from", default=now)
+        limit = parse_integer(request, "limit", default=100)
+        room_id = parse_string(request, "room_id")
+        user_id = parse_string(request, "user_id")
+
+        if start < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST,
+                "The start parameter must be a positive integer.",
+                errcode=Codes.INVALID_PARAM,
+            )
+
+        if limit < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST,
+                "The limit parameter must be a positive integer.",
+                errcode=Codes.INVALID_PARAM,
+            )
+
+        room_reports, total = await self._store.get_room_reports_paginate(
+            start, limit, user_id, room_id
+        )
+
+        ret = {}
+        has_more = len(room_reports) > limit
+        # trim the extra room if it exists
+        room_reports = room_reports[:limit]
+        if has_more:
+            ret["next_batch"] = room_reports[-1]["received_ts"]
+
+        ret.update({"room_reports": room_reports, "total": total})
+
+        return HTTPStatus.OK, ret
+
+
+class RoomReportDetailRestServlet(RestServlet):
+    """
+    Get a specific reported room that is known to the homeserver. Results are returned
+    in a dictionary containing report information.
+    The requester must have administrator access in Synapse.
+
+    GET /_synapse/admin/v1/room_reports/<report_id>
+    returns:
+        200 OK with details report if success otherwise an error.
+
+    Args:
+        The parameter `report_id` is the ID of the room report in the database.
+    Returns:
+        JSON blob of information about the room report
+    """
+
+    PATTERNS = admin_patterns("/room_reports/(?P<report_id>[^/]*)$")
+
+    def __init__(self, hs: "HomeServer"):
+        self._auth = hs.get_auth()
+        self._store = hs.get_datastores().main
+
+    async def on_GET(
+        self, request: SynapseRequest, report_id: str
+    ) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        message = (
+            "The report_id parameter must be a string representing a positive integer."
+        )
+        try:
+            resolved_report_id = int(report_id)
+        except ValueError:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        ret = await self._store.get_room_report(resolved_report_id)
+        if not ret:
+            raise NotFoundError("Room report not found")
+
+        return HTTPStatus.OK, ret
+
+    async def on_DELETE(
+        self, request: SynapseRequest, report_id: str
+    ) -> tuple[int, JsonDict]:
+        await assert_requester_is_admin(self._auth, request)
+
+        message = (
+            "The report_id parameter must be a string representing a positive integer."
+        )
+        try:
+            resolved_report_id = int(report_id)
+        except ValueError:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        if resolved_report_id < 0:
+            raise SynapseError(
+                HTTPStatus.BAD_REQUEST, message, errcode=Codes.INVALID_PARAM
+            )
+
+        if await self._store.delete_room_report(resolved_report_id):
+            return HTTPStatus.OK, {}
+
+        raise NotFoundError("Room report not found")