# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DocuSign Rooms API - v2 Roles API
  version: 1.0.0
extends: openapi/docusign-roles-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v2/accounts/{accountId}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List company roles
      effect: read
      questions:
      - What company roles are defined in my Rooms account?
      - Can I list only the roles I'm allowed to assign?
      instructions:
      - text: List company roles for account {account}.
        slots:
          account: path.accountId
      - text: List assignable roles in account {account} matching {filter}.
        slots:
          account: path.accountId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/accounts/{accountId}/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a company role
      effect: write
      questions:
      - How do I create a new role for my company account?
      - Can I make a role for external users with specific permissions?
      instructions:
      - text: Create a role named {name} in account {account}.
        slots:
          name: requestBody.name
          account: path.accountId
      - text: 'Create role {name} with permissions {permissions}, external: {isExternal}.'
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
          isExternal: requestBody.isExternal
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/accounts/{accountId}/roles/{roleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company role and its permissions
      effect: read
      questions:
      - What permissions does a specific role include?
      - Is a given role currently assigned to anyone?
      instructions:
      - text: Get role {role} in account {account}.
        slots:
          role: path.roleId
          account: path.accountId
      - text: 'Show role {role} and whether it is assigned: {includeIsAssigned}.'
        slots:
          role: path.roleId
          includeIsAssigned: query.includeIsAssigned
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/accounts/{accountId}/roles/{roleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a company role
      effect: write
      questions:
      - How do I change the permissions on an existing role?
      - Can I rename a company role?
      instructions:
      - text: Rename role {role} in account {account} to {name}.
        slots:
          role: path.roleId
          account: path.accountId
          name: requestBody.name
      - text: Set the permissions of role {role} to {permissions}.
        slots:
          role: path.roleId
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/accounts/{accountId}/roles/{roleId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a company role
      effect: destructive
      questions:
      - How do I delete a role from my company account?
      - What permission do I need to remove a role?
      instructions:
      - text: Delete role {role} from account {account}.
        slots:
          role: path.roleId
          account: path.accountId
      - text: Remove company role {role}.
        slots:
          role: path.roleId
      method: generated
      generated: '2026-10-01'