From 2b68fd935c6c81e96eb5c63d88454c3c47106e96 Mon Sep 17 00:00:00 2001 From: Logan Devine Date: Tue, 2 Jun 2026 04:56:07 -0700 Subject: [PATCH] Specify Mutual Rooms (MSC2666) (#2367) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Logan Devine 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> --- .../client_server/newsfragments/2367.new | 1 + content/client-server-api/_index.md | 2 + .../client-server-api/modules/mutual_rooms.md | 19 +++ data/api/client-server/mutual_rooms.yaml | 127 ++++++++++++++++++ 4 files changed, 149 insertions(+) create mode 100644 changelogs/client_server/newsfragments/2367.new create mode 100644 content/client-server-api/modules/mutual_rooms.md create mode 100644 data/api/client-server/mutual_rooms.yaml diff --git a/changelogs/client_server/newsfragments/2367.new b/changelogs/client_server/newsfragments/2367.new new file mode 100644 index 00000000..88520ba9 --- /dev/null +++ b/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). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 4cdb84ac..ed7e1e9f 100644 --- a/content/client-server-api/_index.md +++ b/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" %}} diff --git a/content/client-server-api/modules/mutual_rooms.md b/content/client-server-api/modules/mutual_rooms.md new file mode 100644 index 00000000..162e9c71 --- /dev/null +++ b/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. diff --git a/data/api/client-server/mutual_rooms.yaml b/data/api/client-server/mutual_rooms.yaml new file mode 100644 index 00000000..2d764e6c --- /dev/null +++ b/data/api/client-server/mutual_rooms.yaml @@ -0,0 +1,127 @@ +# Copyright 2026 Logan Devine +# +# 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