Specify Mutual Rooms (MSC2666) (#2367)

Signed-off-by: Logan Devine <logan@zirco.dev>
Co-authored-by: Kévin Commaille <76261501+zecakeh@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

changelogs/client_server/newsfragments/2367.new

@@ -0,0 +1 @@
+Add `GET /_matrix/client/v1/mutual_rooms`, as per [MSC2666](https://github.com/matrix-org/matrix-spec-proposals/pull/2666).

content/client-server-api/_index.md

@@ -4302,6 +4302,7 @@ that profile.
 | [Third-party Networks](#third-party-networks)              | Optional  | Optional | Optional | Optional | Optional |
 | [Threading](#threading)                                    | Optional  | Optional | Optional | Optional | Optional |
 | [Invite permission](#invite-permission)                    | Optional  | Optional | Optional | Optional | Optional |
+| [Mutual Rooms](#mutual-rooms)                              | Optional  | Optional | Optional | Optional | Optional |
 
 *Please see each module for more details on what clients need to
 implement.*
@@ -4392,3 +4393,4 @@ systems.
 {{% cs-module name="Recently used emoji" filename="recent_emoji" %}}
 {{% cs-module name="Threading" filename="threading" %}}
 {{% cs-module name="Reference relations" filename="reference_relations" %}}
+{{% cs-module name="Mutual Rooms" filename="mutual_rooms" %}}

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

@@ -0,0 +1,19 @@
+### Mutual Rooms
+
+{{% added-in v="1.19" %}}
+
+{{% http-api spec="client-server" api="mutual_rooms" %}}
+
+#### Server behaviour
+
+The server may decide that the response to this endpoint is too large, and only return a
+subset of the results. In this case, the server should populate the optional field `next_batch`
+with an [opaque identifier](/appendices/#opaque-identifiers). The client may then supply
+the identifier as the `from` query parameter in a subsequent request, along with the original
+`user_id`, to fetch the next batch of responses. This will continue until the server no longer
+inserts `next_batch`, meaning there are no further results.
+
+Batch tokens generated by this endpoint SHOULD be valid for at least 10 minutes, after which,
+tokens can expire. Expired tokens SHOULD be handled similar to invalid tokens, and return
+a 400 response. When a client uses batch tokens, servers MAY omit rooms that the user joined
+after the first token was generated.

data/api/client-server/mutual_rooms.yaml

@@ -0,0 +1,127 @@
+# Copyright 2026 Logan Devine <logan@zirco.dev>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Mutual Rooms API
+  version: 1.0.0
+paths:
+  /mutual_rooms:
+    get:
+      summary: Get the list of rooms that the user shares with another user.
+      description: |-
+        Get the list of rooms that the user shares with another user. The
+        server will return a list of room IDs that the user shares with the
+        specified `user_id`.
+      operationId: getMutualRooms
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: user_id
+          required: true
+          description: The MXID of the user to check for mutual rooms with.
+          example: "@alice:example.com"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+        - in: query
+          name: from
+          required: false
+          description: |-
+            A pagination token from a previous result. This should be a `next_batch` result from
+            a previous call to this endpoint. If not provided, the server will return the first
+            batch of results.
+          example: next_batch_token
+          schema:
+            type: string
+      responses:
+        "200":
+          description: |-
+            A list of room IDs that the user shares with the specified user.
+            If the provided `user_id` is not a valid user, the server MUST return an empty list of rooms.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - joined
+                  - count
+                properties:
+                  joined:
+                    type: array
+                    description: |-
+                      A list of room IDs where both the authenticated user and `user_id` have a
+                      membership of type `join`.
+                    items:
+                      type: string
+                      format: mx-room-id
+                      pattern: "^!"
+                      example: "!OGEhHVWSdvArJzumhm:matrix.org"
+                  count:
+                    type: integer
+                    description: |-
+                      The number of such rooms. This is the total count even if the response is
+                      batched and `joined` doesn't include all rooms. This MAY be inaccurate
+                      if the server is unable to calculate the exact number of rooms.
+                    example: 1
+                  next_batch:
+                    type: string
+                    description: |-
+                      A pagination token to retrieve the next batch of results. This will be absent
+                      if there are no more results to return.
+                    example: next_batch_token
+
+        "400":
+          description: |-
+            Part of the request was invalid. The `from` token provided was invalid or expired,
+            the `user_id` parameter was missing, [non-compliant](/appendices/#historical-user-ids),
+            or was the sender's own user ID.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "The user ID provided was invalid"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Mutual Rooms
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer