diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml
index ef89ce5193..93253565f1 100644
--- a/zerver/openapi/zulip.yaml
+++ b/zerver/openapi/zulip.yaml
@@ -1699,7 +1699,7 @@ paths:
                             - type: object
                               description: |
                                 Event sent to a user's clients when that user's set of
-                                configured muted users have changed.
+                                configured [muted users](/api/mute-user) have changed.
 
                                 **Changes**: New in Zulip 4.0 (feature level 48).
                               properties:
@@ -5767,6 +5767,30 @@ paths:
 
         `POST {{ api_url }}/v1/users/me/muted_users/{muted_user_id}`
 
+        Muted users should be implemented by clients as follows:
+
+        * The server will immediately mark all messages sent by the muted
+          user as read.  This will automatically clear any existing mobile
+          push notifications related to the muted user.
+        * The server will mark any new messages sent by the muted user as read
+          for your account, which prevents all email and mobile push notifications.
+        * Clients should exclude muted users from presence lists or other UI
+          for viewing or composing 1:1 private messages. 1:1 private messages sent by
+          muted users should be hidden everywhere in the Zulip UI.
+        * Stream messages and group private messages sent by the muted
+          user should avoid displaying the content and name/avatar,
+          but should display that N messages by a muted user were
+          hidden (so that it is possible to interpret the messages by
+          other users who are talking with the muted user).
+        * Group private message conversations including the muted user
+          should display muted users as "Muted user", rather than
+          showing their name, in lists of such conversations, along with using
+          a blank grey avatar where avatars are displayed.
+        * Administrative/settings UI elements for showing "All users that exist
+          on this stream or realm", e.g. for organization
+          administration or showing stream subscribers, should display
+          the user's name as normal.
+
         **Changes**: New in Zulip 4.0 (feature level 48).
       parameters:
         - $ref: "#/components/parameters/MutedUserId"
@@ -7058,7 +7082,7 @@ paths:
                           Present if `muted_users` is present in `fetch_event_types`.
 
                           A list of dictionaries where each dictionary describes
-                          a muted user.
+                          a [muted user](/api/mute-user).
 
                           **Changes**: New in Zulip 4.0 (feature level 48).
                         items: