# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian Users API
  version: 1.0.0
extends: openapi/atlassian-users-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: 37
- target: $.paths['/v1/orgs/{orgId}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List managed accounts in an organization
      effect: read
      questions:
      - Which user accounts does my Atlassian organization manage?
      - Can I page through every managed account in an org with a cursor?
      instructions:
      - text: List the managed accounts in organization {orgId}.
        slots:
          orgId: path.orgId
      - text: Get the next page of managed accounts in org {orgId} after cursor {cursor}.
        slots:
          orgId: path.orgId
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in an organization directory
      effect: read
      questions:
      - Who are the users in a specific directory of my organization?
      - Can I list directory members one page at a time?
      instructions:
      - text: List the users in directory {directoryId} of org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
      - text: Continue listing directory {directoryId} users in org {orgId} from cursor {cursor}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one user's details in a directory
      effect: read
      questions:
      - What details does the org directory hold for a single user account?
      - Can I look up one person in a directory by their account ID?
      instructions:
      - text: Show directory details for account {accountId} in directory {directoryId} of org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
          accountId: path.accountId
      - text: Pull up the directory record for user {accountId} (org {orgId}, directory {directoryId}).
        slots:
          accountId: path.accountId
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a user from a directory
      effect: destructive
      questions:
      - How do I take someone out of a directory in my Atlassian organization?
      - Is removing a user from a directory different from suspending them?
      instructions:
      - text: Remove account {accountId} from directory {directoryId} in org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
          accountId: path.accountId
      - text: Take user {accountId} out of org {orgId}'s directory {directoryId}.
        slots:
          accountId: path.accountId
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count the users in a directory
      effect: read
      questions:
      - How many users are in one of my organization's directories?
      - Can I get just a headcount for a directory without listing everyone?
      instructions:
      - text: Count the users in directory {directoryId} of org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
      - text: Tell me how many people are in org {orgId}'s directory {directoryId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/users/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite people to an organization
      effect: write
      questions:
      - Can I invite several people to my organization by email at once?
      - Is it possible to put invitees straight into groups and product roles when inviting them?
      instructions:
      - text: Invite {emails} to organization {orgId}.
        slots:
          emails: requestBody.emails
          orgId: path.orgId
      - text: Invite {emails} to org {orgId} and add them to groups {groupIds}.
        slots:
          emails: requestBody.emails
          orgId: path.orgId
          groupIds: requestBody.groupIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/suspend'].post
  update:
    x-apievangelist-phrasing:
      intent: Suspend a user's access in a directory
      effect: destructive
      questions:
      - How do I temporarily cut off a user's access without removing them?
      - Can access be suspended for just one directory in the organization?
      instructions:
      - text: Suspend access for account {accountId} in directory {directoryId} of org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
          accountId: path.accountId
      - text: Temporarily block user {accountId} in org {orgId}'s directory {directoryId}.
        slots:
          accountId: path.accountId
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore a suspended user's access
      effect: write
      questions:
      - How do I give a suspended user their access back?
      - Can I reactivate someone I suspended in a directory?
      instructions:
      - text: Restore access for suspended account {accountId} in directory {directoryId} of org {orgId}.
        slots:
          orgId: path.orgId
          directoryId: path.directoryId
          accountId: path.accountId
      - text: Lift the suspension on user {accountId} in org {orgId}'s directory {directoryId}.
        slots:
          accountId: path.accountId
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/orgs/{orgId}/users/{userId}/roles/assign'].post
  update:
    x-apievangelist-phrasing:
      intent: Grant a user product access via roles
      effect: write
      questions:
      - How can I give a user access to Jira or Confluence from the organization admin?
      - Which roles do I pass to grant someone product access?
      instructions:
      - text: Grant user {userId} in org {orgId} product access with roles {roles}.
        slots:
          userId: path.userId
          orgId: path.orgId
          roles: requestBody.roles
      - text: Give user {userId} in org {orgId} the product roles {roles}.
        slots:
          userId: path.userId
          orgId: path.orgId
          roles: requestBody.roles
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/orgs/{orgId}/users/{userId}/roles/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Revoke a user's product access
      effect: destructive
      questions:
      - Can I take away a user's access to a specific Atlassian product?
      - What happens to product access when I remove a user's product roles?
      instructions:
      - text: Revoke product roles {roles} from user {userId} in org {orgId}.
        slots:
          roles: requestBody.roles
          userId: path.userId
          orgId: path.orgId
      - text: Take away product access {roles} from user {userId} in org {orgId}.
        slots:
          roles: requestBody.roles
          userId: path.userId
          orgId: path.orgId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/orgs/{orgId}/directories/{directoryId}/users/{accountId}/role-assignments'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's role assignments
      effect: read
      questions:
      - Which roles is a particular directory user assigned?
      - Can I audit what roles one person holds in my organization?
      instructions:
      - text: List role assignments for account {accountId} in directory {directoryId} of org {orgId}.
        slots:
          accountId: path.accountId
          directoryId: path.directoryId
          orgId: path.orgId
      - text: Show which roles user {accountId} holds in org {orgId}'s directory {directoryId}.
        slots:
          accountId: path.accountId
          orgId: path.orgId
          directoryId: path.directoryId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/orgs/{orgId}/users/{userId}/role-assignments/assign'].post
  update:
    x-apievangelist-phrasing:
      intent: Assign an organization-level role to a user
      effect: write
      questions:
      - How do I make a user an organization admin-level role holder?
      - Can I assign an org-wide role rather than a product role?
      instructions:
      - text: Assign organization role {role} to user {userId} in org {orgId}.
        slots:
          role: requestBody.role
          userId: path.userId
          orgId: path.orgId
      - text: Make user {userId} an org-level {role} in organization {orgId}.
        slots:
          role: requestBody.role
          userId: path.userId
          orgId: path.orgId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/orgs/{orgId}/users/{userId}/role-assignments/revoke'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove an organization-level role from a user
      effect: destructive
      questions:
      - Can I strip an org-level role from a user while leaving their product access?
      - What's the way to demote someone from an organization role?
      instructions:
      - text: Remove organization role {role} from user {userId} in org {orgId}.
        slots:
          role: requestBody.role
          userId: path.userId
          orgId: path.orgId
      - text: Revoke the org-level {role} role held by user {userId} in organization {orgId}.
        slots:
          role: requestBody.role
          userId: path.userId
          orgId: path.orgId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the signed-in Bitbucket user
      effect: read
      questions:
      - Who am I authenticated as in Bitbucket?
      - Can I check which Bitbucket account my token belongs to?
      instructions:
      - text: Show my Bitbucket user profile.
      - text: Tell me which Bitbucket account is currently logged in.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/emails'].get
  update:
    x-apievangelist-phrasing:
      intent: List my Bitbucket email addresses
      effect: read
      questions:
      - Which email addresses are on my Bitbucket account, including unconfirmed ones?
      - Can I see all the emails tied to my own Bitbucket login?
      instructions:
      - text: List all email addresses on my Bitbucket account.
      - text: Show my confirmed and unconfirmed Bitbucket emails.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/user/emails/{email}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check one of my Bitbucket email addresses
      effect: read
      questions:
      - Is a given email on my Bitbucket account confirmed?
      - Can I tell whether a specific address is my primary Bitbucket email?
      instructions:
      - text: Check whether {email} is confirmed and primary on my Bitbucket account.
        slots:
          email: path.email
      - text: Show the details of my Bitbucket email {email}.
        slots:
          email: path.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{selected_user}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Bitbucket user's public profile
      effect: read
      questions:
      - What public profile info can I see for another Bitbucket user?
      - Why are location and website missing from some Bitbucket user profiles?
      instructions:
      - text: Get the public Bitbucket profile for {selected_user}.
        slots:
          selected_user: path.selected_user
      - text: Look up Bitbucket user {selected_user} and show their public info.
        slots:
          selected_user: path.selected_user
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Confluence user by account ID
      effect: read
      questions:
      - How can I look up a Confluence user's display name and profile picture?
      - Can I fetch a Confluence user record from their account ID?
      instructions:
      - text: Get the Confluence user with account ID {accountId}.
        slots:
          accountId: query.accountId
      - text: Fetch Confluence user {accountId} expanded with {expand}.
        slots:
          accountId: query.accountId
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/anonymous'].get
  update:
    x-apievangelist-phrasing:
      intent: See how Confluence shows anonymous users
      effect: read
      questions:
      - What display name and picture does Confluence use for anonymous visitors?
      - Can I see how anonymous users are represented on my Confluence site?
      instructions:
      - text: Show how anonymous users are represented in Confluence.
      - text: Get the Confluence anonymous user representation expanded with {expand}.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/current'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the logged-in Confluence user
      effect: read
      questions:
      - Which Confluence account is my API call running as?
      - Can I get my own Confluence userKey and account ID?
      instructions:
      - text: Show the currently logged-in Confluence user.
      - text: Get my Confluence user details expanded with {expand}.
        slots:
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/memberof'].get
  update:
    x-apievangelist-phrasing:
      intent: List a Confluence user's group memberships
      effect: read
      questions:
      - Which Confluence groups does a given user belong to?
      - Can I page through a user's Confluence group memberships?
      instructions:
      - text: List the Confluence groups that account {accountId} is a member of.
        slots:
          accountId: query.accountId
      - text: Show up to {limit} Confluence groups that user {accountId} belongs to.
        slots:
          limit: query.limit
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several Confluence users at once
      effect: read
      questions:
      - Can I fetch details for many Confluence users in one request?
      - Is there a limit on how many Confluence users a bulk lookup returns?
      instructions:
      - text: Look up Confluence user details for account IDs {accountId}.
        slots:
          accountId: query.accountId
      - text: Fetch up to {limit} Confluence users in bulk for IDs {accountId}.
        slots:
          limit: query.limit
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/email'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Confluence user's email address
      effect: read
      questions:
      - Can an approved app read a Confluence user's email address?
      - Why does reading a Confluence user's email need Atlassian approval?
      instructions:
      - text: Get the Confluence email address for account {accountId}.
        slots:
          accountId: query.accountId
      - text: Look up the email of Confluence user {accountId} for my approved app.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/user/email/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Confluence email addresses in a batch
      effect: read
      questions:
      - Can my approved app pull Confluence email addresses for a set of account IDs at once?
      - What's the batch way to read several Confluence users' emails?
      instructions:
      - text: Get Confluence email addresses for accounts {accountId} in one batch.
        slots:
          accountId: query.accountId
      - text: Batch-fetch Confluence user emails for the account IDs {accountId}.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Jira user
      effect: read
      questions:
      - How do I look up a Jira user by account ID?
      - Why might a Jira user's email be hidden when I fetch them?
      instructions:
      - text: Get the Jira user with account ID {accountId}.
        slots:
          accountId: query.accountId
      - text: Fetch Jira user {accountId} including {expand}.
        slots:
          accountId: query.accountId
          expand: query.expand
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Jira user
      effect: write
      questions:
      - Can I add a new user to Jira by email address through the API?
      - Which Jira products can I give a user when I create them?
      instructions:
      - text: Create a Jira user for {emailAddress}.
        slots:
          emailAddress: requestBody.emailAddress
      - text: Create Jira user {emailAddress} with access to products {products}.
        slots:
          emailAddress: requestBody.emailAddress
          products: requestBody.products
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user from Jira
      effect: destructive
      questions:
      - Does deleting a user from Jira also delete their Atlassian account?
      - Who is allowed to remove a user from Jira's user base?
      instructions:
      - text: Delete Jira user {accountId}.
        slots:
          accountId: query.accountId
      - text: Remove account {accountId} from Jira's user base, keeping their Atlassian account.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several Jira users by account ID
      effect: read
      questions:
      - Can I fetch a batch of Jira users by their account IDs in one call?
      - What's the paginated way to resolve a list of Jira account IDs to users?
      instructions:
      - text: Get the Jira users with account IDs {accountId}.
        slots:
          accountId: query.accountId
      - text: Get up to {maxResults} Jira users for account IDs {accountId}.
        slots:
          maxResults: query.maxResults
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/bulk/migration'].get
  update:
    x-apievangelist-phrasing:
      intent: Map Jira usernames or keys to account IDs
      effect: read
      questions:
      - How do I convert old Jira usernames into account IDs?
      - Can I look up account IDs for several user keys at once during a migration?
      instructions:
      - text: Get account IDs for Jira usernames {username}.
        slots:
          username: query.username
      - text: Resolve Jira user keys {key} to account IDs.
        slots:
          key: query.key
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/columns'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's default issue table columns
      effect: read
      questions:
      - Which issue table columns does a Jira user see by default?
      - Can I read my own default issue navigator columns?
      instructions:
      - text: Show my default Jira issue table columns.
      - text: Get the default issue table columns for account {accountId}.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/columns'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a user's default issue table columns
      effect: write
      questions:
      - Can I choose which columns appear by default in a user's Jira issue table?
      - What happens if I send no columns when setting a user's defaults?
      instructions:
      - text: Set my default issue table columns to {columns}.
        slots:
          columns: requestBody.columns
      - text: Set default issue table columns {columns} for account {accountId}.
        slots:
          columns: requestBody.columns
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/columns'].delete
  update:
    x-apievangelist-phrasing:
      intent: Reset a user's issue table columns to default
      effect: destructive
      questions:
      - How do I put a user's Jira issue table columns back to the system default?
      - Can I undo custom column choices for my own issue table?
      instructions:
      - text: Reset my issue table columns to the system default.
      - text: Reset the issue table columns for account {accountId} to the system default.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/email'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Jira user's email address
      effect: read
      questions:
      - Can an approved app read the email address of a single Jira user?
      - Which apps are allowed to see a Jira user's email?
      instructions:
      - text: Get the Jira email address for account {accountId}.
        slots:
          accountId: query.accountId
      - text: Look up the email of Jira user {accountId} for my approved app.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/email/bulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get Jira user email addresses in bulk
      effect: read
      questions:
      - Can my approved app read emails for several Jira accounts in a single call?
      - Is there a bulk version of the Jira user email lookup?
      instructions:
      - text: Get Jira email addresses for accounts {accountId} in bulk.
        slots:
          accountId: query.accountId
      - text: Bulk-fetch Jira user emails for account IDs {accountId}.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/groups'].get
  update:
    x-apievangelist-phrasing:
      intent: List the Jira groups a user belongs to
      effect: read
      questions:
      - Which Jira groups is a given user a member of?
      - What permission do I need to see a user's Jira groups?
      instructions:
      - text: List the Jira groups for account {accountId}.
        slots:
          accountId: query.accountId
      - text: Show which Jira groups user {accountId} is in.
        slots:
          accountId: query.accountId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Jira users (default endpoint)
      effect: read
      questions:
      - Can I list every Jira user, including inactive and deleted ones, from the /users endpoint?
      - Does the default all-users list in Jira include deactivated accounts?
      instructions:
      - text: List all Jira users using the default /users endpoint.
      - text: List {maxResults} Jira users from the default users endpoint starting at {startAt}.
        slots:
          maxResults: query.maxResults
          startAt: query.startAt
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: List all Jira users via the users search endpoint
      effect: read
      questions:
      - What does the Jira users/search endpoint return when I page through everyone?
      - Can I page through all Jira accounts using the users search resource?
      instructions:
      - text: Page through all Jira users with the users/search endpoint.
      - text: Get {maxResults} users from Jira users/search starting at {startAt}.
        slots:
          maxResults: query.maxResults
          startAt: query.startAt
      method: generated
      generated: '2026-10-01'