MSC4151: Reporting rooms

Signed-off-by: Johannes Marbach <n0-0ne+github@mailbox.org>

content/client-server-api/modules/report_content.md

@@ -5,9 +5,6 @@ Users may encounter content which they find inappropriate and should be
 able to report it to the server administrators or room moderators for
 review. This module defines a way for users to report content.
 
-Content is reported based upon a negative score, where -100 is "most
-offensive" and 0 is "inoffensive".
-
 #### Client behaviour
 
 {{% http-api spec="client-server" api="report_content" %}}
@@ -19,6 +16,16 @@ This may be a dedicated room to alert server administrators to the
 reported content or some other mechanism for notifying the appropriate
 people.
 
-{{< changed-in v="1.8" >}} The server MUST verify that the user 
-reporting the event is currently joined to the room the event is 
-in before accepting a report.
+Particularly during waves of a harmful content, users may report whole
+rooms instead of individual events. Server administrators and safety teams
+should, therefore, be cautious not to shut down rooms that might otherwise
+be legitimate.
+
+{{< changed-in v="1.8" >}} When processing event reports, servers MUST
+verify that the reporting user is currently joined to the room the event
+is in before accepting a report.
+
+Contrarily, servers MUST NOT restrict room reports based on whether or not the
+reporting user is joined to the room. This is because users can be exposed
+to harmful content without being joined to a room, for instance, through
+room directories.

data/api/client-server/report_content.yaml

@@ -16,6 +16,69 @@ info:
   title: Matrix Client-Server Report Content API
   version: 1.0.0
 paths:
+  "/rooms/{roomId}/report":
+    post:
+      summary: Report a room as inappropriate.
+      description: |-
+        Reports a room as inappropriate to the server, which may then notify
+        the appropriate people. The caller is not required to be joined to the
+        room to report it.
+      operationId: reportRoom
+      parameters:
+        - in: path
+          name: roomId
+          description: The room being reported.
+          required: true
+          example: "!637q39766251:example.com"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "this makes me sad"
+              }
+              properties:
+                reason:
+                  type: string
+                  description: The reason the room is being reported.
+        required: true
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The room has been reported successfully.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: |-
+            The room was not found on the homeserver.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "The room was not found."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Reporting content
   "/rooms/{roomId}/report/{eventId}":
     post:
       summary: Report an event in a joined room as inappropriate.
@@ -29,7 +92,7 @@ paths:
         will require the homeserver to check whether a user is joined to
         the room. To combat this, homeserver implementations should add
         a random delay when generating a response.
-      operationId: reportContent
+      operationId: reportEvent
       parameters:
         - in: path
           name: roomId
@@ -62,7 +125,7 @@ paths:
                     and 0 is inoffensive.
                 reason:
                   type: string
-                  description: The reason the content is being reported. May be blank.
+                  description: The reason the content is being reported.
         required: true
       security:
         - accessTokenQuery: []