MSC4151: Reporting rooms (#1938)

Author: Johennes

changelogs/client_server/newsfragments/1938.clarification

@@ -0,0 +1 @@
+The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414).

changelogs/client_server/newsfragments/1938.new

@@ -0,0 +1 @@
+Add `POST /_matrix/client/v3/rooms/{roomId}/report` as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151).

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 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.
+
+{{< added-in v="1.12" >}} 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 or invites.

data/api/client-server/report_content.yaml

@@ -16,6 +16,71 @@ info:
   title: Matrix Client-Server Report Content API
   version: 1.0.0
 paths:
+  "/rooms/{roomId}/report":
+    post:
+      x-addedInMatrixVersion: "1.12"
+      summary: Report a room as inappropriate.
+      description: |-
+        Reports a room as inappropriate to the server, which may then notify
+        the appropriate people. How such information is delivered is left up to
+        implementations. 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 +94,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 +127,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: []