# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for dotCMS REST Roles API
  version: 1.0.0
extends: openapi/dotcms-roles-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 19
- target: $.paths['/api/role/loadbyid/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Load full role details (legacy endpoint)
      effect: read
      questions:
      - How did the old admin UI load a role's full properties by id?
      - Is there a deprecated endpoint that returns every property of a role?
      instructions:
      - text: Load role details with the deprecated loadbyid endpoint using {params}.
        slots:
          params: path.params
      - text: Fetch the role via the legacy loadbyid call for {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/role/loadbyname/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Filter the role tree by name (legacy endpoint)
      effect: read
      questions:
      - Can I get a role tree trimmed to leaves whose name contains some text on the old API?
      - Which deprecated call filters the role tree by name?
      instructions:
      - text: Filter the role tree by name using the legacy loadbyname call with {params}.
        slots:
          params: path.params
      - text: Get the deprecated name-filtered role tree for {params}.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/role/loadchildren/{params}'].get
  update:
    x-apievangelist-phrasing:
      intent: Lazy-load a role's children (legacy endpoint)
      effect: read
      questions:
      - How does the deprecated API return the first-level children of a role?
      - What does the legacy loadchildren call return when no role id is given?
      instructions:
      - text: Load first-level child roles with the legacy loadchildren call for {params}.
        slots:
          params: path.params
      - text: Expand the old role tree node {params} one level down.
        slots:
          params: path.params
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List the top-level roles
      effect: read
      questions:
      - What are the root roles in my dotCMS role hierarchy?
      - Can I get the root roles with their children included?
      instructions:
      - text: List the root roles.
      - text: Show root roles with children loaded set to {loadChildrenRoles}.
        slots:
          loadChildrenRoles: query.loadChildrenRoles
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new role
      effect: write
      questions:
      - How do I create a new role under an existing parent role?
      - Can I let a new role edit users or permissions when I create it?
      instructions:
      - text: Create a role named {roleName}.
        slots:
          roleName: requestBody.roleName
      - text: Create role {roleName} under parent {parentRoleId} with key {roleKey}.
        slots:
          roleName: requestBody.roleName
          parentRoleId: requestBody.parentRoleId
          roleKey: requestBody.roleKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}/users/{userId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a role to a user
      effect: write
      questions:
      - How do I give a user a role directly?
      - What happens if I grant a role the user already has?
      instructions:
      - text: Grant role {roleid} to user {userId}.
        slots:
          roleid: path.roleid
          userId: path.userId
      - text: Add user {userId} as a direct member of role {roleid}.
        slots:
          userId: path.userId
          roleid: path.roleid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/checkuserroles/userid/{userId}/roleids/{roleIds}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if a user holds any of given roles
      effect: read
      questions:
      - Does this user belong to at least one of these roles?
      - How can I verify a user's role membership against a list of role ids?
      instructions:
      - text: Check whether user {userId} has any of the roles {roleIds}.
        slots:
          userId: path.userId
          roleIds: path.roleIds
      - text: Verify {userId} is assigned one of {roleIds}.
        slots:
          userId: path.userId
          roleIds: path.roleIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role by its id
      effect: read
      questions:
      - How do I look up a single role by id on the v1 API?
      - Can I include the child roles when fetching one role?
      instructions:
      - text: Get role {roleid}.
        slots:
          roleid: path.roleid
      - text: Fetch role {roleid} with its child roles set to {loadChildrenRoles}.
        slots:
          roleid: path.roleid
          loadChildrenRoles: query.loadChildrenRoles
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an existing role's settings
      effect: write
      questions:
      - How do I rename a role or move it under a different parent?
      - Does updating a role overwrite fields I leave out of the request?
      instructions:
      - text: Rename role {roleid} to {roleName}.
        slots:
          roleid: path.roleid
          roleName: requestBody.roleName
      - text: Update role {roleid} as {roleName} and move it under parent {parentRoleId}.
        slots:
          roleid: path.roleid
          roleName: requestBody.roleName
          parentRoleId: requestBody.parentRoleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role and its grants
      effect: destructive
      questions:
      - What happens to users and permissions when I delete a role?
      - Can a deleted role be restored?
      instructions:
      - text: Delete role {roleid}.
        slots:
          roleid: path.roleid
      - text: Remove role {roleid} along with its permissions and user memberships.
        slots:
          roleid: path.roleid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/layouts'].get
  update:
    x-apievangelist-phrasing:
      intent: List all tool-group layouts
      effect: read
      questions:
      - Which tool groups (layouts) exist in the backend?
      - What layouts could I assign to a role?
      instructions:
      - text: List every layout in the system.
      - text: Show all tool groups available for roles.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/layouts'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign layouts to a role
      effect: write
      questions:
      - How do I give a role access to certain backend tool groups?
      - Can I add several layouts to a role in one call?
      instructions:
      - text: Assign layouts {layoutIds} to role {roleId}.
        slots:
          layoutIds: requestBody.layoutIds
          roleId: requestBody.roleId
      - text: Give role {roleId} the tool groups {layoutIds}.
        slots:
          roleId: requestBody.roleId
          layoutIds: requestBody.layoutIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/layouts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove layouts from a role
      effect: destructive
      questions:
      - How do I take tool groups away from a role?
      - Can I unassign several layouts from a role at once?
      instructions:
      - text: Remove layouts {layoutIds} from role {roleId}.
        slots:
          layoutIds: requestBody.layoutIds
          roleId: requestBody.roleId
      - text: Revoke tool groups {layoutIds} from role {roleId}.
        slots:
          layoutIds: requestBody.layoutIds
          roleId: requestBody.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleId}/layouts'].get
  update:
    x-apievangelist-phrasing:
      intent: List the layouts assigned to a role
      effect: read
      questions:
      - Which tool groups does this role currently have?
      - What backend layouts are attached to a given role?
      instructions:
      - text: Show the layouts assigned to role {roleId}.
        slots:
          roleId: path.roleId
      - text: List tool groups for role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/users/{userIdOrEmail}'].get
  update:
    x-apievangelist-phrasing:
      intent: List the roles a user holds
      effect: read
      questions:
      - Which roles does a given user have?
      - Can I look up a user's roles by email address?
      instructions:
      - text: List the roles for user {userIdOrEmail}.
        slots:
          userIdOrEmail: path.userIdOrEmail
      - text: Show what roles {userIdOrEmail} is in.
        slots:
          userIdOrEmail: path.userIdOrEmail
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}/rolehierarchyanduserroles'].get
  update:
    x-apievangelist-phrasing:
      intent: Load a role's hierarchy and user roles
      effect: read
      questions:
      - How do I see a role's hierarchy together with the user roles under it?
      - Can I filter a role's hierarchy and user roles by name?
      instructions:
      - text: Load the role hierarchy and user roles for {roleid}.
        slots:
          roleid: path.roleid
      - text: Show hierarchy and user roles under {roleid} filtered by {name}.
        slots:
          roleid: path.roleid
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users directly granted a role
      effect: read
      questions:
      - Who are the users directly assigned to this role?
      - Does the role member list include users who inherit it through the hierarchy?
      instructions:
      - text: List the users directly granted role {roleid}.
        slots:
          roleid: path.roleid
      - text: Show page {page} of role {roleid} members matching {filter}.
        slots:
          page: query.page
          roleid: path.roleid
          filter: query.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/{roleid}/users'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove users from a role in bulk
      effect: destructive
      questions:
      - How do I take several users out of a role at once?
      - What happens if some of the users in a bulk role removal aren't members?
      instructions:
      - text: Remove users {userIds} from role {roleid}.
        slots:
          userIds: requestBody.userIds
          roleid: path.roleid
      - text: Revoke the direct membership of {userIds} in role {roleid}.
        slots:
          userIds: requestBody.userIds
          roleid: path.roleid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/roles/_search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search roles by name, key or id
      effect: read
      questions:
      - How do I search for roles whose name matches some text?
      - Can a role search include workflow roles and user roles?
      instructions:
      - text: Search roles named like {searchName}.
        slots:
          searchName: query.searchName
      - text: Find roles with key {searchKey}, including workflow roles set to {includeWorkflowRoles}.
        slots:
          searchKey: query.searchKey
          includeWorkflowRoles: query.includeWorkflowRoles
      method: generated
      generated: '2026-09-26'