From 0b8f025d214d0edb7e23e6d59a5c4a0d25e03ebe Mon Sep 17 00:00:00 2001 From: timedout Date: Sat, 11 Apr 2026 20:33:15 +0100 Subject: [PATCH 1/2] Initial draft Signed-off-by: timedout --- proposals/4449-get-members-filters.md | 50 +++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 proposals/4449-get-members-filters.md diff --git a/proposals/4449-get-members-filters.md b/proposals/4449-get-members-filters.md new file mode 100644 index 00000000000..e99a3b2fc31 --- /dev/null +++ b/proposals/4449-get-members-filters.md @@ -0,0 +1,50 @@ +# MSC4449: Updated /members filtering + +Currently, [`GET /_matrix/client/v3/rooms/{roomId}/members`][s1] only allows filtering up to one +kind of membership per filter. +This means clients can only request members who match a specific membership, or do not match a +specific membership. This proposal aims to make this endpoint more intuitive and useful by allowing +the filters to match against multiple memberships. + +[s1]: https://spec.matrix.org/v1.18/client-server-api/#get_matrixclientv3roomsroomidmembers + +## Proposal + +Building on the art of [MSC2895](https://github.com/matrix-org/matrix-spec-proposals/pull/2895), +this proposal will move spearhead one of the options proposed. + +As it appears to be the least complex change, the `membership` and `not_membership` query parameters +are updated to allow being provided multiple times, to specify multiple matches. For example, +specifying `?membership=join&membership=invite` will yield all memberships of kinds `join`, *or* +`invite`. Specifying `?not_membership=leave¬_membership=ban` will yield all memberships that are +NOT of kinds `leave` or `ban` (so, at the time of writing, `join`, `invite`, or `knock`). + +As part of this change, they are also made *mutually exclusive*. Specifying both `membership` and +`not_membership` in the same query is explicitly forbidden, and will return `400 / M_INVALID_PARAM`. + +## Potential issues + +This change re-uses existing parameter names and may confuse older servers if newer clients try to +request data with the updated filter behaviour. In order to attempt to reduce this collision, +clients should check for the unstable feature or relevant spec version (if merged) in `/versions` +before using the updated behaviour. + +## Alternatives + +As mentioned, [MSC2895](https://github.com/matrix-org/matrix-spec-proposals/pull/2895) provides some +ideas for further changes to the members endpoint, alongside some other ones. + +## Security considerations + +None + +## Unstable prefix + +Implementations should use `uk.timedout.msc4449.membership` and `uk.timedout.msc4449.not_membership` +as query parameters for the duration of the proposal's unstable period. Servers *SHOULD* advertise +`uk.timedout.msc4449` in `/_matrix/client/versions` too, so that clients will know they can use the +new parameters. + +## Dependencies + +None From a74d3dcca9d78ce8d1bfb9b5599896532266a4ae Mon Sep 17 00:00:00 2001 From: timedout Date: Sat, 11 Apr 2026 20:40:44 +0100 Subject: [PATCH 2/2] Typo --- proposals/4449-get-members-filters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4449-get-members-filters.md b/proposals/4449-get-members-filters.md index e99a3b2fc31..8c9efc75c3f 100644 --- a/proposals/4449-get-members-filters.md +++ b/proposals/4449-get-members-filters.md @@ -11,7 +11,7 @@ the filters to match against multiple memberships. ## Proposal Building on the art of [MSC2895](https://github.com/matrix-org/matrix-spec-proposals/pull/2895), -this proposal will move spearhead one of the options proposed. +this proposal will spearhead one of the options proposed. As it appears to be the least complex change, the `membership` and `not_membership` query parameters are updated to allow being provided multiple times, to specify multiple matches. For example,