# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Dex Roles API
  version: 1.0.0
extends: openapi/controlup-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: 5
- target: $.paths['/organizations/{orgId}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles in the organization
      effect: read
      questions:
      - Which roles exist in my ControlUp organization?
      - Can I list only the default roles, or roles for one child organization?
      instructions:
      - text: List all roles in organization {orgId}.
        slots:
          orgId: path.orgId
      - text: Find roles named {name} in organization {orgId}.
        slots:
          name: query.name
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{orgId}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a custom role with specific permissions?
      - Can I assign users and groups to a role while creating it?
      instructions:
      - text: Create role {name} in organization {orgId}.
        slots:
          name: requestBody.name
          orgId: path.orgId
      - text: Create role {name} in {orgId} with permissions {permissions} and assign users {usersIdsToAssign}.
        slots:
          name: requestBody.name
          orgId: path.orgId
          permissions: requestBody.permissions
          usersIdsToAssign: requestBody.usersIdsToAssign
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{orgId}/roles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role's permissions and assignees
      effect: read
      questions:
      - What permissions does a specific role grant?
      - Which users are assigned a particular role?
      instructions:
      - text: Get role {id} in organization {orgId}.
        slots:
          id: path.id
          orgId: path.orgId
      - text: Show the permissions and assigned users of role {id} in {orgId}.
        slots:
          id: path.id
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{orgId}/roles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - What happens to users assigned a role when I delete it?
      - How do I remove a role from my organization?
      instructions:
      - text: Delete role {id} from organization {orgId}.
        slots:
          id: path.id
          orgId: path.orgId
      - text: Remove role {id} in {orgId} and unassign it from everyone.
        slots:
          id: path.id
          orgId: path.orgId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{orgId}/roles/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a role
      effect: write
      questions:
      - How do I add or remove users from an existing role?
      - Can I change the permissions of a role I already created?
      instructions:
      - text: Assign users {usersIdsToAssign} to existing role {id} in {orgId}.
        slots:
          id: path.id
          orgId: path.orgId
          usersIdsToAssign: requestBody.usersIdsToAssign
      - text: Remove groups {groupsIdsToRemove} from role {id} in organization {orgId}.
        slots:
          groupsIdsToRemove: requestBody.groupsIdsToRemove
          id: path.id
          orgId: path.orgId
      - text: Replace the permissions of role {id} in {orgId} with {permissions}.
        slots:
          id: path.id
          orgId: path.orgId
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'