Skip to content

MSC4449: Updated /members filtering #4449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
timedoutuk wants to merge 2 commits into
base: main
Choose a base branch
from
+50 −0
Open

MSC4449: Updated /members filtering #4449

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b8f025
Initial draft
timedoutuk Apr 11, 2026
a74d3dc
Typo
timedoutuk Apr 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 50 additions & 0 deletions proposals/4449-get-members-filters.md
View file
Open in desktop
Copy link
Copy Markdown
Member

@turt2live turt2live Apr 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implementation requirements:

  • Client (using)
  • Server (offering)

Original file line number Diff line number Diff line change
@@ -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 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&not_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`.
Comment on lines +22 to +23
Copy link
Copy Markdown
Member

@clokep clokep Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is not_membership even needed anymore?

Copy link
Copy Markdown
Contributor Author

@timedoutuk timedoutuk Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a nice shortcut to be able to specify you want all but a certain membership (for example, not ban + leave gives you everyone who is invited, knocking, or joined), otherwise you have to manually specify every membership you do want. I'd also be fine with just dropping it, I just didn't think it was important.


## 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.
Comment on lines +27 to +30
Copy link
Copy Markdown
Member

@clokep clokep Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a reason to rev the endpoint version?

Copy link
Copy Markdown
Contributor Author

@timedoutuk timedoutuk Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably, especially if not_membership gets removed, but I wanted to get some feedback before deciding that.


## 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
Loading