# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Auth0 Management Roles API
  version: 1.0.0
extends: openapi/auth0-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: 10
- target: $.paths['/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles in a tenant
      effect: read
      questions:
      - Which roles have I created in my tenant?
      - Can I search roles by name?
      instructions:
      - text: List my roles.
      - text: Find roles named {name_filter}.
        slots:
          name_filter: query.name_filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new role for role-based access control?
      - Does a new role get any permissions by default?
      instructions:
      - text: Create a role {name}.
        slots:
          name: requestBody.name
      - text: Create role {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role by ID
      effect: read
      questions:
      - Can I see the name and description of one role?
      - What are the details of a specific role ID?
      instructions:
      - text: Show role {id}.
        slots:
          id: path.id
      - text: Get details of role {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - What happens to users who had a role when I delete it?
      - How do I delete a role?
      instructions:
      - text: Delete role {id}.
        slots:
          id: path.id
      - text: Remove role {id} from the tenant.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or describe a role
      effect: write
      questions:
      - Can I rename an existing role?
      - How do I change a role's description?
      instructions:
      - text: Rename role {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set the description of role {id} to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List permissions granted by a role
      effect: read
      questions:
      - Which permissions does a role grant?
      - Can I see the resource server behind each permission of a role?
      instructions:
      - text: List permissions of role {id}.
        slots:
          id: path.id
      - text: Show what role {id} is allowed to do.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}/permissions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add permissions to a role
      effect: write
      questions:
      - How do I add API permissions to a role?
      - Can I attach several permissions to a role in one go?
      instructions:
      - text: Add permissions {permissions} to role {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      - text: Grant role {id} the scopes {permissions}.
        slots:
          id: path.id
          permissions: requestBody.permissions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}/permissions'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove permissions from a role
      effect: destructive
      questions:
      - How do I take a permission away from a role?
      - Can I strip several scopes from a role at once?
      instructions:
      - text: Remove permissions {permissions} from role {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      - text: Revoke scopes {permissions} on role {id}.
        slots:
          permissions: requestBody.permissions
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users who have a role
      effect: read
      questions:
      - Which users are assigned a particular role?
      - Can I page through everyone holding a role with a checkpoint?
      instructions:
      - text: List users with role {id}.
        slots:
          id: path.id
      - text: Show {take} members of role {id}.
        slots:
          take: query.take
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/roles/{id}/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign users to a role
      effect: write
      questions:
      - How do I add several users to a role at once?
      - Can I bulk-assign a role to a list of users?
      instructions:
      - text: Assign users {users} to role {id}.
        slots:
          users: requestBody.users
          id: path.id
      - text: Add {users} as members of role {id}.
        slots:
          users: requestBody.users
          id: path.id
      method: generated
      generated: '2026-10-01'