From dcdfd84f27e716acfc01167315d651604cf97742 Mon Sep 17 00:00:00 2001
From: Hugh Nimmo-Smith <hughns@element.io>
Date: Wed, 17 Sep 2025 18:08:56 +0100
Subject: [PATCH] Add note where an endpoint uses capability negotiation

---
 .../client_server/newsfragments/2223.clarification   |  1 +
 data/api/client-server/administrative_contact.yaml   | 12 ++++++++++++
 data/api/client-server/password_management.yaml      |  4 ++++
 data/api/client-server/profile.yaml                  |  5 +++++
 4 files changed, 22 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/2223.clarification

diff --git a/changelogs/client_server/newsfragments/2223.clarification b/changelogs/client_server/newsfragments/2223.clarification
new file mode 100644
index 000000000..401a1f95c
--- /dev/null
+++ b/changelogs/client_server/newsfragments/2223.clarification
@@ -0,0 +1 @@
+Add note to each endpoint that uses capability negotiation.
diff --git a/data/api/client-server/administrative_contact.yaml b/data/api/client-server/administrative_contact.yaml
index 54b91d42d..357125953 100644
--- a/data/api/client-server/administrative_contact.yaml
+++ b/data/api/client-server/administrative_contact.yaml
@@ -99,6 +99,10 @@ paths:
         has been removed, making this endpoint behave as though it was `false`.
         This results in this endpoint being an equivalent to `/3pid/bind` rather
         than dual-purpose.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: post3PIDs
       deprecated: true
       security:
@@ -202,6 +206,10 @@ paths:
         Homeservers should prevent the caller from adding a 3PID to their account if it has
         already been added to another user's account on the homeserver.
 
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
+
         {{% boxes/warning %}}
         Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained
         via the [OAuth 2.0 API](/client-server-api/#oauth-20-api).
@@ -331,6 +339,10 @@ paths:
         Unlike other endpoints, this endpoint does not take an `id_access_token`
         parameter because the homeserver is expected to sign the request to the
         identity server instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.3pid_changes` capability](/client-server-api/#m3pid_changes-capability)
+        to determine if this endpoint is available.
       operationId: delete3pidFromAccount
       security:
         - accessTokenQuery: []
diff --git a/data/api/client-server/password_management.yaml b/data/api/client-server/password_management.yaml
index bf310ff94..b2d60559b 100644
--- a/data/api/client-server/password_management.yaml
+++ b/data/api/client-server/password_management.yaml
@@ -34,6 +34,10 @@ paths:
         valid access token is provided. The homeserver SHOULD NOT revoke the
         access token provided in the request. Whether other access tokens for
         the user are revoked depends on the request parameters.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation).
+        Clients SHOULD check the value of the [`m.change_password` capability](/client-server-api/#mchange_password-capability)
+        to determine if this endpoint is available.
       security:
         - {}
         - accessTokenQuery: []
diff --git a/data/api/client-server/profile.yaml b/data/api/client-server/profile.yaml
index 9f872fe8f..4e34503a2 100644
--- a/data/api/client-server/profile.yaml
+++ b/data/api/client-server/profile.yaml
@@ -29,6 +29,11 @@ paths:
         Servers MAY reject `null` values. Servers that accept `null` values SHOULD store
         them rather than treating `null` as a deletion request. Clients that want to delete a
         field, including its key and value, SHOULD use the `DELETE` endpoint instead.
+
+        This endpoint uses [capabilities negotiation](/client-server-api/#capabilities-negotiation)
+        depending on the `keyName`. Clients SHOULD check the value of the
+        [`m.profile_fields` capability](/client-server-api/#mprofile_fields-capability) to detect
+        which `keyName`s they are allowed to modify.
       operationId: setProfileField
       security:
         - accessTokenQuery: []