From 57adbed0763f62fa745ac60f8e4f481d4313425c Mon Sep 17 00:00:00 2001 From: wiggin77 Date: Fri, 10 Apr 2026 11:20:32 -0400 Subject: [PATCH 1/5] Add documentation for bulk set channel members API Add setChannelMembers audit event to the audit log schema and document the new PUT /api/v4/channels/{channel_id}/members endpoint in the team and channel members admin guide. Introduced in Mattermost v11.7. --- .../comply/embedded-json-audit-log-schema.rst | 2 ++ .../manage/team-channel-members.rst | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/source/administration-guide/comply/embedded-json-audit-log-schema.rst b/source/administration-guide/comply/embedded-json-audit-log-schema.rst index 2aef0ffb666..75a0d4d5675 100644 --- a/source/administration-guide/comply/embedded-json-audit-log-schema.rst +++ b/source/administration-guide/comply/embedded-json-audit-log-schema.rst @@ -256,6 +256,8 @@ Channel Management Events +------------------------------------+-------------------------------------------------------------------+ | ``removeChannelMember`` | Removing members from channels | +------------------------------------+-------------------------------------------------------------------+ +| ``setChannelMembers`` | Bulk set (replace) channel memberships | ++------------------------------------+-------------------------------------------------------------------+ | ``restoreChannel`` | Restoring deleted channels | +------------------------------------+-------------------------------------------------------------------+ | ``updateChannel`` | Updating channel information | diff --git a/source/administration-guide/manage/team-channel-members.rst b/source/administration-guide/manage/team-channel-members.rst index e5c10338204..e4d4f854cea 100644 --- a/source/administration-guide/manage/team-channel-members.rst +++ b/source/administration-guide/manage/team-channel-members.rst @@ -153,3 +153,21 @@ A list of all members in a channel is visible to system admins. Members can be a - Member - Channel admin - System admin + +Bulk set channel members via the API +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*Available from Mattermost v11.7* + +System admins can set the complete membership of a channel in a single API call using ``PUT /api/v4/channels/{channel_id}/members``. The request body is a JSON array of user IDs representing the desired membership. The server computes the diff against the current membership and adds or removes users as needed, leaving existing members untouched. + +Results are streamed back as NDJSON (``application/x-ndjson``), one line per batch. Each line contains ``added``, ``removed``, and ``errors`` arrays for that batch. Query parameters ``batch_size`` (default 100) and ``batch_delay_ms`` (default 500) control the processing rate. + +Restrictions: + +- Requires ``manage_system`` permission (system admin only). +- DM/GM and group-constrained channels are rejected. +- Private channels cannot be emptied entirely. +- Request body is limited to 12 MB. + +See the `API documentation `__ for full details. From f4b4dbc515ffd479b657c788a8bb8bd56d916f1c Mon Sep 17 00:00:00 2001 From: wiggin77 Date: Fri, 10 Apr 2026 11:26:35 -0400 Subject: [PATCH 2/5] Added example --- .../manage/team-channel-members.rst | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/source/administration-guide/manage/team-channel-members.rst b/source/administration-guide/manage/team-channel-members.rst index e4d4f854cea..5fddd43ece9 100644 --- a/source/administration-guide/manage/team-channel-members.rst +++ b/source/administration-guide/manage/team-channel-members.rst @@ -163,6 +163,28 @@ System admins can set the complete membership of a channel in a single API call Results are streamed back as NDJSON (``application/x-ndjson``), one line per batch. Each line contains ``added``, ``removed``, and ``errors`` arrays for that batch. Query parameters ``batch_size`` (default 100) and ``batch_delay_ms`` (default 500) control the processing rate. +**Example** + +Request (using ``batch_size=2`` and ``batch_delay_ms=200``): + +.. code-block:: bash + + curl -X PUT \ + 'https://mattermost.example.com/api/v4/channels/channel123/members?batch_size=2&batch_delay_ms=200' \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '["user_id_1", "user_id_2", "user_id_3", "user_id_4"]' + +Streamed NDJSON response (one JSON object per line, one line per batch): + +.. code-block:: text + + {"added":[],"removed":["user_id_5","user_id_6"],"errors":[]} + {"added":["user_id_3","user_id_4"],"removed":[],"errors":[]} + {"added":[],"removed":[],"errors":[{"user_id":"user_id_7","error":"user is not a member of the team"}]} + +In this example, ``user_id_1`` and ``user_id_2`` were already members (no-op), ``user_id_5`` and ``user_id_6`` were removed, ``user_id_3`` and ``user_id_4`` were added, and ``user_id_7`` could not be added because the user is not on the team. + Restrictions: - Requires ``manage_system`` permission (system admin only). From 97582c39b8f4eeef28161715bb8acb2b09677ad8 Mon Sep 17 00:00:00 2001 From: wiggin77 Date: Wed, 15 Apr 2026 00:52:09 -0400 Subject: [PATCH 3/5] Removed examples, which are now in the API docs. --- .../manage/team-channel-members.rst | 37 +------------------ 1 file changed, 2 insertions(+), 35 deletions(-) diff --git a/source/administration-guide/manage/team-channel-members.rst b/source/administration-guide/manage/team-channel-members.rst index 5fddd43ece9..5e424992e74 100644 --- a/source/administration-guide/manage/team-channel-members.rst +++ b/source/administration-guide/manage/team-channel-members.rst @@ -157,39 +157,6 @@ A list of all members in a channel is visible to system admins. Members can be a Bulk set channel members via the API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -*Available from Mattermost v11.7* +.. note:: -System admins can set the complete membership of a channel in a single API call using ``PUT /api/v4/channels/{channel_id}/members``. The request body is a JSON array of user IDs representing the desired membership. The server computes the diff against the current membership and adds or removes users as needed, leaving existing members untouched. - -Results are streamed back as NDJSON (``application/x-ndjson``), one line per batch. Each line contains ``added``, ``removed``, and ``errors`` arrays for that batch. Query parameters ``batch_size`` (default 100) and ``batch_delay_ms`` (default 500) control the processing rate. - -**Example** - -Request (using ``batch_size=2`` and ``batch_delay_ms=200``): - -.. code-block:: bash - - curl -X PUT \ - 'https://mattermost.example.com/api/v4/channels/channel123/members?batch_size=2&batch_delay_ms=200' \ - -H 'Authorization: Bearer ' \ - -H 'Content-Type: application/json' \ - -d '["user_id_1", "user_id_2", "user_id_3", "user_id_4"]' - -Streamed NDJSON response (one JSON object per line, one line per batch): - -.. code-block:: text - - {"added":[],"removed":["user_id_5","user_id_6"],"errors":[]} - {"added":["user_id_3","user_id_4"],"removed":[],"errors":[]} - {"added":[],"removed":[],"errors":[{"user_id":"user_id_7","error":"user is not a member of the team"}]} - -In this example, ``user_id_1`` and ``user_id_2`` were already members (no-op), ``user_id_5`` and ``user_id_6`` were removed, ``user_id_3`` and ``user_id_4`` were added, and ``user_id_7`` could not be added because the user is not on the team. - -Restrictions: - -- Requires ``manage_system`` permission (system admin only). -- DM/GM and group-constrained channels are rejected. -- Private channels cannot be emptied entirely. -- Request body is limited to 12 MB. - -See the `API documentation `__ for full details. + From Mattermost v11.7, system admins can set the complete membership of a channel in a single API call. The server computes the diff against the current membership and adds or removes users as needed. See the `API documentation `__ for details. From e3f6303586283125e6134f4a89620c0e9bdaa09c Mon Sep 17 00:00:00 2001 From: Eric Sethna <14333569+esethna@users.noreply.github.com> Date: Thu, 16 Apr 2026 07:50:41 -0700 Subject: [PATCH 4/5] Update team-channel-members.rst --- source/administration-guide/manage/team-channel-members.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/administration-guide/manage/team-channel-members.rst b/source/administration-guide/manage/team-channel-members.rst index 5e424992e74..f7c6c1c68e6 100644 --- a/source/administration-guide/manage/team-channel-members.rst +++ b/source/administration-guide/manage/team-channel-members.rst @@ -154,9 +154,6 @@ A list of all members in a channel is visible to system admins. Members can be a - Channel admin - System admin -Bulk set channel members via the API -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. note:: From Mattermost v11.7, system admins can set the complete membership of a channel in a single API call. The server computes the diff against the current membership and adds or removes users as needed. See the `API documentation `__ for details. From 80b9f69e4d86d7c035cfb030b6d59f29475ffa44 Mon Sep 17 00:00:00 2001 From: Doug Lauder Date: Fri, 17 Apr 2026 15:05:03 -0400 Subject: [PATCH 5/5] Apply suggestion from @wiggin77 --- source/administration-guide/manage/team-channel-members.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration-guide/manage/team-channel-members.rst b/source/administration-guide/manage/team-channel-members.rst index f7c6c1c68e6..fdb041ebd03 100644 --- a/source/administration-guide/manage/team-channel-members.rst +++ b/source/administration-guide/manage/team-channel-members.rst @@ -156,4 +156,4 @@ A list of all members in a channel is visible to system admins. Members can be a .. note:: - From Mattermost v11.7, system admins can set the complete membership of a channel in a single API call. The server computes the diff against the current membership and adds or removes users as needed. See the `API documentation `__ for details. + From Mattermost v11.5.2, system admins can set the complete membership of a channel in a single API call. The server computes the diff against the current membership and adds or removes users as needed. See the `API documentation `__ for details.