From f9fcab129dbe3daf1a77a404575e46252b47e94f Mon Sep 17 00:00:00 2001
From: Logan Devine <logan@zirco.dev>
Date: Thu, 30 Apr 2026 11:22:59 -0700
Subject: [PATCH] Specify Mutual Rooms (MSC2666)

Signed-off-by: Logan Devine <logan@zirco.dev>
---
 .../client_server/newsfragments/2367.feature  |   2 +
 content/client-server-api/_index.md           |   4 +
 data/api/client-server/mutual_rooms.yaml      | 118 ++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/2367.feature
 create mode 100644 data/api/client-server/mutual_rooms.yaml

diff --git a/changelogs/client_server/newsfragments/2367.feature b/changelogs/client_server/newsfragments/2367.feature
new file mode 100644
index 00000000..7b470b14
--- /dev/null
+++ b/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).
diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md
index 4cdb84ac..7a82406c 100644
--- a/content/client-server-api/_index.md
+++ b/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
diff --git a/data/api/client-server/mutual_rooms.yaml b/data/api/client-server/mutual_rooms.yaml
new file mode 100644
index 00000000..1a7583c4
--- /dev/null
+++ b/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