diff --git a/data/deprecations/17-0-custom-role-creation.yml b/data/deprecations/17-0-custom-role-creation.yml
index d1c4387f0a0033f6f3286a8bb5035470fc2458bc..5e1cc4f3a1027a26b7a2532a0985c01fa5dce168 100644
--- a/data/deprecations/17-0-custom-role-creation.yml
+++ b/data/deprecations/17-0-custom-role-creation.yml
@@ -10,3 +10,9 @@
     Group Owners will be able to assign custom roles at the group level.
 
     Group owners on GitLab.com can continue to manage custom roles and assign at the group level.
+
+    If using the API to manage custom roles on a self-managed instance, a new instance endpoint has been added and is required to continue API operations.
+
+    - List all member roles on the instance - `GET /api/v4/member_roles`
+    - Add member role to the instance - `POST /api/v4/member_roles`
+    - Remove member role from the instance - `DELETE /api/v4/member_roles/:id`
diff --git a/doc/update/deprecations.md b/doc/update/deprecations.md
index 21939395cf6eec3be47a3441e535e4fd0b425339..d0eba77dfe830e5c35bf24f3165ac50be3a2494f 100644
--- a/doc/update/deprecations.md
+++ b/doc/update/deprecations.md
@@ -932,6 +932,12 @@ Group Owners will be able to assign custom roles at the group level.
 
 Group owners on GitLab.com can continue to manage custom roles and assign at the group level.
 
+If using the API to manage custom roles on a self-managed instance, a new instance endpoint has been added and is required to continue API operations.
+
+- List all member roles on the instance - `GET /api/v4/member_roles`
+- Add member role to the instance - `POST /api/v4/member_roles`
+- Remove member role from the instance - `DELETE /api/v4/member_roles/:id`
+
 </div>
 
 <div class="deprecation breaking-change" data-milestone="17.0">