# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for BigPanda Roles & Permissions API
  version: 1.0.0
extends: openapi/bigpanda-roles-permissions-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: 12
- target: $.paths['/resources/v2.1/roles/{role_id}/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Add users to a role in bulk
      effect: write
      questions:
      - Can I add a whole team of users to a role in one call when onboarding?
      - How do I bulk-assign users to an existing BigPanda role?
      instructions:
      - text: Add these users to role {role_id}.
        slots:
          role_id: path.role_id
      - text: Bulk-assign the new team members to role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles/{role_id}/users'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove users from a role
      effect: destructive
      questions:
      - Can I take several users out of a role at once?
      - What removes people from a role without deleting the role itself?
      instructions:
      - text: Remove these users from role {role_id}.
        slots:
          role_id: path.role_id
      - text: Take the departing team members out of role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles with sorting and paging (v2.1)
      effect: read
      questions:
      - Can I page through my roles sorted by a field using the v2.1 Roles API?
      - Can I sort the v2.1 role list ascending or descending?
      instructions:
      - text: List v2.1 roles sorted by {sort} in {direction} order.
        slots:
          sort: query.sort
          direction: query.direction
      - text: Show page {page} of v2.1 roles with {per_page} per page.
        slots:
          page: query.page
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a role
      effect: write
      questions:
      - How do I create a new role with a specific set of permissions?
      - Can I add users to a role at the moment I create it?
      instructions:
      - text: Create a role named {name} with permissions {permissions}.
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
      - text: Create role {name} granting {permissions} to users {users}.
        slots:
          name: requestBody.name
          permissions: requestBody.permissions
          users: requestBody.users
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles/{role_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role by ID (v2.1)
      effect: read
      questions:
      - Can I fetch one role's users and permissions from the v2.1 Roles API?
      - What does a specific v2.1 role currently contain?
      instructions:
      - text: Get v2.1 role {role_id}.
        slots:
          role_id: path.role_id
      - text: Show the name, users and permissions of v2.1 role {role_id}.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles/{role_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a role's name, users and permissions
      effect: write
      questions:
      - Do I have to send the full list of users and permissions every time I replace a role?
      - Can I overwrite a role's whole definition in a single call?
      instructions:
      - text: Replace role {role_id} with name {name} and permissions {permissions}.
        slots:
          role_id: path.role_id
          name: requestBody.name
          permissions: requestBody.permissions
      - text: Overwrite role {role_id} so it is {name} with users {users} and permissions {permissions}.
        slots:
          role_id: path.role_id
          name: requestBody.name
          users: requestBody.users
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles/{role_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a role
      effect: destructive
      questions:
      - How do I delete a role we no longer use?
      - Can I remove a role from BigPanda completely?
      instructions:
      - text: Delete role {role_id}.
        slots:
          role_id: path.role_id
      - text: Remove role {role_id} from the system.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/roles/{role_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a role in place
      effect: write
      questions:
      - Can I tweak just one property of a role without resending the whole definition?
      - Is there a partial update for a role's permissions?
      instructions:
      - text: Patch role {role_id} with only the changed properties.
        slots:
          role_id: path.role_id
      - text: Adjust a single permission on role {role_id} in place.
        slots:
          role_id: path.role_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List all roles and permissions (legacy endpoint)
      effect: read
      questions:
      - Can I get every role with its permissions from the older /roles endpoint?
      - What roles does my organization have, according to the legacy roles endpoint?
      instructions:
      - text: List all roles and their permissions from the legacy roles endpoint.
      - text: Pull every organization role from the older /roles endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{roleId}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users who hold a role
      effect: read
      questions:
      - Who has a particular role in BigPanda?
      - Can I list all the users associated with one role?
      instructions:
      - text: List the users assigned to role {roleId}.
        slots:
          roleId: path.roleId
      - text: Show me everyone who holds role {roleId}.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/roles/{roleId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a role (legacy endpoint)
      effect: read
      questions:
      - Can I look up a role and its permissions through the older /roles endpoint?
      - What permissions does a role have according to the legacy roles API?
      instructions:
      - text: Get role {roleId} from the legacy roles endpoint.
        slots:
          roleId: path.roleId
      - text: Show the permissions on role {roleId} using the older /roles API.
        slots:
          roleId: path.roleId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: List available permissions
      effect: read
      questions:
      - Which permissions and actions can I grant to a role?
      - What permissions are available given my environments and feature toggles?
      instructions:
      - text: List all permissions available to assign.
      - text: Show every permission with its allowed actions.
      method: generated
      generated: '2026-09-26'