# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Atlassian The Jira Cloud platform REST User Search API
  version: 1.0.0
extends: openapi/atlassian-user-search-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: 8
- target: $.paths['/rest/api/3/user/assignable/multiProjectSearch'].get
  update:
    x-apievangelist-phrasing:
      intent: Find users assignable across several projects
      effect: read
      questions:
      - Who can be assigned issues in all of these Jira projects?
      - Can I search assignable users across multiple projects at once?
      instructions:
      - text: Find users assignable to issues in projects {projectKeys}.
        slots:
          projectKeys: query.projectKeys
      - text: Search for {query} among users assignable in projects {projectKeys}.
        slots:
          query: query.query
          projectKeys: query.projectKeys
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/assignable/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find users assignable to an issue
      effect: read
      questions:
      - Who can I assign this particular issue to?
      - Which users can take a new issue in a given project?
      instructions:
      - text: List users who can be assigned issue {issueKey}.
        slots:
          issueKey: query.issueKey
      - text: Find assignable users matching {query} for new issues in project {project}.
        slots:
          query: query.query
          project: query.project
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/permission/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find users holding specific permissions
      effect: read
      questions:
      - Which users have both edit and transition permission on a project?
      - Can I find who holds a set of permissions on a specific issue?
      instructions:
      - text: Find users with permissions {permissions} in project {projectKey}.
        slots:
          permissions: query.permissions
          projectKey: query.projectKey
      - text: List users holding {permissions} on issue {issueKey}.
        slots:
          permissions: query.permissions
          issueKey: query.issueKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/picker'].get
  update:
    x-apievangelist-phrasing:
      intent: Search users for a picker with highlights
      effect: read
      questions:
      - How do I build a user autocomplete that highlights the matched text?
      - Can I exclude certain accounts from user picker suggestions?
      instructions:
      - text: Suggest users for a picker matching {query}.
        slots:
          query: query.query
      - text: Return up to {maxResults} picker suggestions for {query}, excluding {excludeAccountIds}.
        slots:
          maxResults: query.maxResults
          query: query.query
          excludeAccountIds: query.excludeAccountIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find active users by name, email or property
      effect: read
      questions:
      - Is there a Jira user with this email address?
      - Can I find active users by a user property value?
      instructions:
      - text: Find active users matching {query}.
        slots:
          query: query.query
      - text: Search users whose property matches {property}.
        slots:
          property: query.property
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/search/query'].get
  update:
    x-apievangelist-phrasing:
      intent: Find user details with a structured query
      effect: read
      questions:
      - Can I search users with a structured query such as is assignee of a project?
      - Which users match a structured query over their properties?
      instructions:
      - text: Return user details for users matching structured query {query}.
        slots:
          query: query.query
      - text: Run structured user query {query}, {maxResults} per page.
        slots:
          query: query.query
          maxResults: query.maxResults
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/search/query/key'].get
  update:
    x-apievangelist-phrasing:
      intent: Find user keys with a structured query
      effect: read
      questions:
      - Can a structured user query return only account keys instead of full profiles?
      - What's the lightweight way to get user keys matching a query?
      instructions:
      - text: Return only the user keys matching structured query {query}.
        slots:
          query: query.query
      - text: List keys for users matching {query}, {maxResult} per page.
        slots:
          query: query.query
          maxResult: query.maxResult
      method: generated
      generated: '2026-10-01'
- target: $.paths['/rest/api/3/user/viewissue/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find users who can browse issues
      effect: read
      questions:
      - Who is able to view this issue?
      - Which users can browse issues in a given project?
      instructions:
      - text: Find users who can view issue {issueKey}.
        slots:
          issueKey: query.issueKey
      - text: List users matching {query} with browse permission in project {projectKey}.
        slots:
          query: query.query
          projectKey: query.projectKey
      method: generated
      generated: '2026-10-01'