Specify Mutual Rooms (MSC2666)

Signed-off-by: Logan Devine <logan@zirco.dev>

changelogs/client_server/newsfragments/2367.feature

@@ -0,0 +1,2 @@
+Specify the `mutual_rooms` API to get rooms in common with another user, as per
+[MSC2666](https://github.com/matrix-org/matrix-spec-proposals/pull/2666).

content/client-server-api/_index.md

@@ -4233,6 +4233,10 @@ users, they should include the display name and avatar URL fields in
 these events so that clients already have these details to hand, and do
 not have to perform extra round trips to query it.
 
+### Mutual Rooms
+
+{{% http-api spec="client-server" api="mutual_rooms" %}}
+
 ## Modules
 
 Modules are parts of the Client-Server API which are not universal to

data/api/client-server/mutual_rooms.yaml

@@ -0,0 +1,118 @@
+# 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
+        - in: query
+          name: from
+          required: false
+          description: A pagination token from a previous result.
+          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
+                      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: |-
+            The user ID provided was [non-compliant](/appendices/#historical-user-ids).
+          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