API Evangelist conversational phrasing for BigPanda Users API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for BigPanda Users API
  version: 1.0.0
extends: openapi/bigpanda-users-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: 26
- target: $.paths['/resources/v2.1/users/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate an invited user account
      effect: write
      questions:
      - How does an invited user finish the invitation flow and become active?
      - Can I activate a user account that was invited but never set up?
      instructions:
      - text: Activate the invited user account to complete their invitation.
      - text: Finish activation for the pending invited user.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/change-password'].post
  update:
    x-apievangelist-phrasing:
      intent: Change a user's password
      effect: write
      questions:
      - Can an admin reset someone's password in BigPanda through the API?
      - Does changing a password require the user's current credentials?
      instructions:
      - text: Change this user's password to the new one I provide.
      - text: Update my password using my current credentials.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List groups via SCIM
      effect: read
      questions:
      - Which groups has my identity provider provisioned over SCIM?
      - What's the rate limit when listing SCIM groups?
      instructions:
      - text: List all SCIM groups in the organization.
      - text: Fetch the SCIM Groups list filtered by my SCIM query.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a group via SCIM
      effect: write
      questions:
      - Can my identity provider create a new group through SCIM provisioning?
      - How do I provision a group with SCIM so members sync from my IdP?
      instructions:
      - text: Create a new SCIM group for the on-call team.
      - text: Provision a group through the SCIM Groups endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users via SCIM
      effect: read
      questions:
      - Which users are provisioned through SCIM right now?
      - Can I filter the SCIM Users list with standard SCIM query parameters?
      instructions:
      - text: List SCIM-provisioned users in the organization.
      - text: Query the SCIM Users resource with my filter.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Users'].post
  update:
    x-apievangelist-phrasing:
      intent: Provision a user via SCIM
      effect: write
      questions:
      - Can I provision a new user from my identity provider with SCIM?
      - What happens when I POST a user to the SCIM Users resource?
      instructions:
      - text: Provision a new user through SCIM.
      - text: Create a SCIM user record for the new hire.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups/{group_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a SCIM group by ID
      effect: read
      questions:
      - How can I see the details and members of one SCIM group?
      - Can I look up a single provisioned group by its SCIM ID?
      instructions:
      - text: Get SCIM group {group_id}.
        slots:
          group_id: path.group_id
      - text: Show the members and details of SCIM group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups/{group_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a SCIM group
      effect: write
      questions:
      - Can I overwrite a SCIM group's full details in one request?
      - Which call replaces the whole group record rather than patching it?
      instructions:
      - text: Replace SCIM group {group_id} with this full group definition.
        slots:
          group_id: path.group_id
      - text: Do a full PUT update of SCIM group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups/{group_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a SCIM group
      effect: destructive
      questions:
      - How do I deprovision a group that was created through SCIM?
      - Can I remove a SCIM group by its ID?
      instructions:
      - text: Delete SCIM group {group_id}.
        slots:
          group_id: path.group_id
      - text: Deprovision the SCIM group with ID {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Groups/{group_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a SCIM group
      effect: write
      questions:
      - Can I add or remove members of a SCIM group without replacing it?
      - Is there a partial update for SCIM groups?
      instructions:
      - text: Patch SCIM group {group_id} to add these members.
        slots:
          group_id: path.group_id
      - text: Partially update only the changed fields of SCIM group {group_id}.
        slots:
          group_id: path.group_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by ID (v2.1 resources)
      effect: read
      questions:
      - Can I fetch one user's record from the v2.1 users resource?
      - What does the v2.1 user lookup return for a given user ID?
      instructions:
      - text: Get user {user_id} from the v2.1 users resource.
        slots:
          user_id: path.user_id
      - text: Look up the v2.1 record for user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user
      effect: destructive
      questions:
      - How do I remove a user from my BigPanda organization?
      - Can I delete a user permanently by their ID?
      instructions:
      - text: Delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Remove the user with ID {user_id} from the organization.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/{user_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Modify a user's details
      effect: write
      questions:
      - Can I change a user's name or other details after they're created?
      - Which call edits an existing user's fields in the v2.1 resource?
      instructions:
      - text: Update user {user_id} with these changed fields.
        slots:
          user_id: path.user_id
      - text: Modify the profile of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/{user_id}/permissions'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's permissions for a product
      effect: read
      questions:
      - What permissions does a given user actually have within a product?
      - Why would the user permissions lookup return 403 for my organization?
      instructions:
      - text: Show the flat permissions of user {user_id} for the product scope.
        slots:
          user_id: path.user_id
      - text: Check what user {user_id} is allowed to do under Central IAM.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: Search users with filters
      effect: read
      questions:
      - Can I find users by name, state or role in one query?
      - Which users were created between two dates?
      - Can I page and sort the filtered user list?
      instructions:
      - text: Find users named {name} with state {state}.
        slots:
          name: query.name
          state: query.state
      - text: List users with role {roleId} created since {since}.
        slots:
          roleId: query.roleId
          since: query.since
      - text: Fetch the users with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user directly
      effect: write
      questions:
      - Can I create a user without sending them an email invitation?
      - What's the v2.1 call to add a new user record?
      instructions:
      - text: Create a new user with the details I provide.
      - text: Add a user record directly in the v2.1 users resource.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a SCIM user by ID
      effect: read
      questions:
      - How can I see a user's SCIM representation by ID?
      - Can my IdP read back a single provisioned user?
      instructions:
      - text: Get SCIM user {user_id}.
        slots:
          user_id: path.user_id
      - text: Read the SCIM record of provisioned user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a SCIM user
      effect: write
      questions:
      - Can I overwrite a provisioned user's full SCIM record?
      - Which SCIM call replaces all of a user's attributes at once?
      instructions:
      - text: Replace SCIM user {user_id} with this full record.
        slots:
          user_id: path.user_id
      - text: Do a full SCIM PUT for user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/scim/v2/Users/{user_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a SCIM user
      effect: write
      questions:
      - Can I deactivate a provisioned user by patching just the active flag over SCIM?
      - Is there a SCIM partial update for a single user attribute?
      instructions:
      - text: Patch SCIM user {user_id} to set active to false.
        slots:
          user_id: path.user_id
      - text: Partially update SCIM user {user_id} with only the changed attributes.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a user by email
      effect: write
      questions:
      - How do I invite a teammate to my BigPanda organization by email?
      - What does an invited user receive after I send the invitation?
      instructions:
      - text: Invite my colleague to the organization by email.
      - text: Send an email invitation to a new team member.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/resources/v2.1/users/invite/resend'].post
  update:
    x-apievangelist-phrasing:
      intent: Resend a pending user invitation
      effect: write
      questions:
      - What if an invited user's invitation expired before they activated?
      - Can I resend the invite email to someone who hasn't activated yet?
      instructions:
      - text: Resend the pending invitation to the user who hasn't activated.
      - text: Send the lapsed invitation email again.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users in the organization
      effect: read
      questions:
      - Who are all the users in my organization?
      - Can I page through the full user list with a page size limit?
      instructions:
      - text: List every user in the organization.
      - text: Get page {page} of users, {limit} per page.
        slots:
          page: query.page
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/activity'].get
  update:
    x-apievangelist-phrasing:
      intent: Check which users were active or inactive
      effect: read
      questions:
      - Which users haven't used the AI Incident Assistant in the last 30 days?
      - What is the default lookback when I don't pass days or a date range?
      - Can I see who was active between two specific dates?
      instructions:
      - text: List users inactive over the last {days} days.
        slots:
          days: query.days
      - text: Show user activity from {from} to {to}.
        slots:
          from: query.from
          to: query.to
      - text: Show only users where active is {active}.
        slots:
          active: query.active
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's roles
      effect: read
      questions:
      - Which roles and permissions are assigned to a specific user?
      - Can I check if someone has the admin role?
      instructions:
      - text: Show the roles assigned to user {userId}.
        slots:
          userId: path.userId
      - text: List role permissions for user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}/roles'].patch
  update:
    x-apievangelist-phrasing:
      intent: Add, remove or replace a user's roles
      effect: write
      questions:
      - Can I add a role to a user without wiping their existing roles?
      - What happens if I remove every role from a user?
      instructions:
      - text: Add roles {roleIds} to user {userId}.
        slots:
          roleIds: requestBody.roleIds
          userId: path.userId
      - text: Apply role action {action} with roles {roleIds} for user {userId}.
        slots:
          action: requestBody.action
          roleIds: requestBody.roleIds
          userId: path.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user with last activity
      effect: read
      questions:
      - When was a particular user last active?
      - Can I retrieve one user including their last activity timestamp?
      instructions:
      - text: Get user {userId} and their last activity time.
        slots:
          userId: path.userId
      - text: Show when user {userId} was last active.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-09-26'