From ec568fb193997abb62fc206183b30ba01498291d Mon Sep 17 00:00:00 2001
From: Alexa Kristensen <81787716+akristen@users.noreply.github.com>
Date: Thu, 3 Sep 2026 09:30:37 -0500
Subject: [PATCH] docs: document Hub API custom role assignment for members and
 teams (#25996)

## Summary
- Document that member `PUT` `role` accepts a custom role **name**, not
only `owner` | `editor` | `member`.
- Document `role` on team `PATCH` (core or custom role name) and on
`org_group` so the PATCH 200 can include the assigned role.
- Add `Editor` to `org_member.role` (title case). Live responses already
return it; the old enum was Owner / Member / Invitee only.

## Test plan
PM must confirm before merge:

- [ ] Member PUT 200: after assigning a custom role (body is not the
previous core role), is `role` still a core value (`Owner` / `Editor` /
`Member`), or is it the custom role **name**? If it is the custom name,
drop the `org_member.role` enum in a follow-up and describe a string
(core or custom name). If it stays a core value, this PR's enum (`Owner`
| `Editor` | `Member` | `Invitee`) is enough.
- [ ] List members: same field. Confirm a user with a custom role lists
as a core value vs the custom name.
- [ ] Casing: request stays lowercase (`editor`); response stays title
case (`Editor`). Confirm that split is real.
- [ ] Team PATCH 200: confirm `org_group.role` is present and is the
value just set (core or custom name).
- [ ] Team assignment is PATCH-only, not PUT.
- [ ] Unknown role names return an error; do not document them as valid.
- [ ] Custom role **name** (not label or UUID) is the request
identifier, matching Docker Home.

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 content/reference/api/hub/changelog.md | 13 ++++++++++++
 content/reference/api/hub/latest.yaml  | 28 ++++++++++++++++++++------
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/content/reference/api/hub/changelog.md b/content/reference/api/hub/changelog.md
index 4ace5936cf..eefbbe9233 100644
--- a/content/reference/api/hub/changelog.md
+++ b/content/reference/api/hub/changelog.md
@@ -15,6 +15,19 @@ issues for Docker Service APIs.
 
 ---
 
+## 2026-09-01
+
+### Updates
+
+- Document that [Update org member (role)](/reference/api/hub/latest/#tag/orgs)
+  accepts a custom role name in `role`.
+- Document the `role` field on
+  [Update some details for an organization group](/reference/api/hub/latest/#tag/groups).
+- Add `Editor` to `org_member.role` on
+  [organization members](/reference/api/hub/latest/#tag/orgs).
+
+---
+
 ## 2026-08-27
 
 ### Updates
diff --git a/content/reference/api/hub/latest.yaml b/content/reference/api/hub/latest.yaml
index 23a3a63def..be60f4a3a6 100644
--- a/content/reference/api/hub/latest.yaml
+++ b/content/reference/api/hub/latest.yaml
@@ -1708,11 +1708,12 @@ paths:
               properties:
                 role:
                   type: string
-                  description: Role of the member
-                  enum:
-                    - owner
-                    - editor
-                    - member
+                  description: |
+                    Role of the member. Valid values are the core roles
+                    `owner`, `editor`, and `member`, or the name of an
+                    existing [custom role](https://docs.docker.com/enterprise/security/roles-and-permissions/custom-roles/manage/).
+                    Use the custom role's name identifier, not its label or UUID.
+                  example: owner
       responses:
         "200":
           description: Member role updated
@@ -1941,6 +1942,13 @@ paths:
                   type: string
                 description:
                   type: string
+                role:
+                  type: string
+                  description: |
+                    Role assigned to the team. Valid values are the core roles
+                    `owner`, `editor`, and `member`, or the name of an
+                    existing [custom role](https://docs.docker.com/enterprise/security/roles-and-permissions/custom-roles/manage/).
+                    Use the custom role's name identifier, not its label or UUID.
       responses:
         "200":
           description: ""
@@ -3664,9 +3672,12 @@ components:
           example: example@docker.com
         role:
           type: string
-          description: User's role in the Organization
+          description: |
+            The member's role in the organization (`Owner`, `Editor`,
+            `Member`, or `Invitee` for pending invites).
           enum:
             - Owner
+            - Editor
             - Member
             - Invitee
           example: Owner
@@ -3750,6 +3761,11 @@ components:
           type: number
           example: 10
           description: Member count of the group
+        role:
+          type: string
+          description: |
+            Role assigned to the team. A core role (`owner`, `editor`, or `member`)
+            or the name of a custom role (not the label or UUID).
     group_member:
       type: object
       properties: