# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Jira Cloud platform REST Users API
  version: 1.0.0
extends: openapi/jira-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: 13
- target: $.paths['/rest/api/3/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's profile
      effect: read
      questions:
      - Can I look up a Jira user's details by account ID?
      - Why might a user's email address be missing from their profile?
      instructions:
      - text: Get the user with account ID {accountId}.
        slots:
          accountId: query.accountId
      - text: Show profile details and groups for user {accountId}.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user
      effect: write
      questions:
      - How do I add a new user and give them access to Jira products?
      - What's required to create a user account through the API?
      instructions:
      - text: Create a user with email {emailAddress} for products {products}.
        slots:
          emailAddress: requestBody.emailAddress
          products: requestBody.products
      - text: Add {emailAddress} as a new user named {displayName} with access to {products}.
        slots:
          emailAddress: requestBody.emailAddress
          displayName: requestBody.displayName
          products: requestBody.products
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user from Jira
      effect: destructive
      questions:
      - Can I remove someone from Jira without deleting their Atlassian account?
      - Who is allowed to delete a Jira user?
      instructions:
      - text: Delete user {accountId} from Jira.
        slots:
          accountId: query.accountId
      - text: Remove account {accountId} from the Jira user base.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several users by account ID
      effect: read
      questions:
      - Can I fetch details for a batch of users in one request?
      - What's the fastest way to resolve a list of account IDs to names?
      instructions:
      - text: Get the users with account IDs {accountId}.
        slots:
          accountId: query.accountId
      - text: Look up display names for accounts {accountId} in bulk.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/bulk/migration'].get
  update:
    x-apievangelist-phrasing:
      intent: Map usernames or keys to account IDs
      effect: read
      questions:
      - How do I convert old usernames or user keys into account IDs?
      - Can I migrate a list of legacy user keys to Atlassian account IDs?
      instructions:
      - text: Get account IDs for usernames {username}.
        slots:
          username: query.username
      - text: Convert user keys {key} to account IDs.
        slots:
          key: query.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/columns'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's default issue columns
      effect: read
      questions:
      - Which issue table columns does a user see by default?
      - Can I check my own default issue navigator columns?
      instructions:
      - text: Get the default issue table columns for user {accountId}.
        slots:
          accountId: query.accountId
      - text: Show my default issue columns.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/columns'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a user's default issue columns
      effect: write
      questions:
      - Can I change which columns a user sees in the issue table by default?
      - What happens if I send no columns when setting a user's defaults?
      instructions:
      - text: Set user {accountId}'s default issue columns to {columns}.
        slots:
          accountId: query.accountId
          columns: requestBody.columns
      - text: Make {columns} my default issue table columns.
        slots:
          columns: requestBody.columns
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/columns'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's issue columns to default
      effect: destructive
      questions:
      - Can I put a user's issue table columns back to the system default?
      - Is there a way to undo custom column settings for someone?
      instructions:
      - text: Reset user {accountId}'s issue columns to the system default.
        slots:
          accountId: query.accountId
      - text: Restore my issue table columns to the defaults.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/email'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's email address
      effect: read
      questions:
      - Can an approved app read a user's email even if their profile hides it?
      - Which apps are allowed to fetch a user's email address?
      instructions:
      - text: Get the email address of user {accountId}.
        slots:
          accountId: query.accountId
      - text: Look up the email for account {accountId} regardless of profile visibility.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/email/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get emails for several users
      effect: read
      questions:
      - Can I fetch email addresses for many account IDs at once?
      - Is there a bulk way to resolve users to their emails?
      instructions:
      - text: Get email addresses for accounts {accountId} in bulk.
        slots:
          accountId: query.accountId
      - text: 'Fetch the emails of all of these users: {accountId}.'
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/user/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List the groups a user belongs to
      effect: read
      questions:
      - Which groups is a user a member of?
      - Can I check whether a user sits in the admins group?
      instructions:
      - text: List the groups user {accountId} belongs to.
        slots:
          accountId: query.accountId
      - text: Show group memberships for account {accountId}.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users from /users
      effect: read
      questions:
      - Can I get a list of every user, including inactive and deleted ones?
      - What does the plain /users listing return compared with the search path?
      instructions:
      - text: List all users, including inactive ones, using the /users endpoint.
      - text: Page through every Jira user from /users starting at {startAt}.
        slots:
          startAt: query.startAt
      method: generated
      generated: '2026-09-26'
- target: $.paths['/rest/api/3/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users from /users/search
      effect: read
      questions:
      - Is there a /users/search listing that returns every account without a query string?
      - Can I page through all active, inactive and deleted users from the users search path?
      instructions:
      - text: List every user via the /users/search endpoint.
      - text: Fetch {maxResults} users at a time from /users/search.
        slots:
          maxResults: query.maxResults
      method: generated
      generated: '2026-09-26'