naftiko: 1.0.0-alpha2
info:
  label: Atlassian The Jira Cloud platform REST API — User Search
  description: 'Atlassian The Jira Cloud platform REST API — User Search. 8 operations. Lead operation: Atlassian Find Users
    Assignable To Projects. Self-contained Naftiko capability covering one Atlassian business surface.'
  tags:
  - Atlassian
  - User Search
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    ATLASSIAN_API_KEY: ATLASSIAN_API_KEY
capability:
  consumes:
  - type: http
    namespace: jira-user-search
    baseUri: https://your-domain.atlassian.net
    description: Atlassian The Jira Cloud platform REST API — User Search business capability. Self-contained, no shared references.
    resources:
    - name: rest-api-3-user-assignable-multiProjectSearch
      path: /rest/api/3/user/assignable/multiProjectSearch
      operations:
      - name: atlassianfindbulkassignableusers
        method: GET
        description: Atlassian Find Users Assignable To Projects
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes, such as `displayName` and `emailAddress`, to
            find relevant users. The string can match the prefix of the
        - name: username
          in: query
          type: string
          description: This parameter is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migr
        - name: accountId
          in: query
          type: string
          description: A query string that is matched exactly against user `accountId`. Required, unless `query` is specified.
        - name: projectKeys
          in: query
          type: string
          description: A list of project keys (case sensitive). This parameter accepts a comma-separated list.
          required: true
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return per page.
    - name: rest-api-3-user-assignable-search
      path: /rest/api/3/user/assignable/search
      operations:
      - name: atlassianfindassignableusers
        method: GET
        description: Atlassian Find Users Assignable To Issues
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes, such as `displayName`, and `emailAddress`,
            to find relevant users. The string can match the prefix of th
        - name: sessionId
          in: query
          type: string
          description: The sessionId of this request. SessionId is the same until the assignee is set.
        - name: username
          in: query
          type: string
          description: This parameter is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migr
        - name: accountId
          in: query
          type: string
          description: A query string that is matched exactly against user `accountId`. Required, unless `query` is specified.
        - name: project
          in: query
          type: string
          description: The project ID or project key (case sensitive). Required, unless `issueKey` is specified.
        - name: issueKey
          in: query
          type: string
          description: The key of the issue. Required, unless `project` is specified.
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return. This operation may return less than the maximum number of items
            even if more are available. The operation fetches users u
        - name: actionDescriptorId
          in: query
          type: integer
          description: The ID of the transition.
        - name: recommend
          in: query
          type: boolean
    - name: rest-api-3-user-permission-search
      path: /rest/api/3/user/permission/search
      operations:
      - name: atlassianfinduserswithallpermissions
        method: GET
        description: Atlassian Find Users With Permissions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes, such as `displayName` and `emailAddress`, to
            find relevant users. The string can match the prefix of the
        - name: username
          in: query
          type: string
          description: This parameter is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migr
        - name: accountId
          in: query
          type: string
          description: A query string that is matched exactly against user `accountId`. Required, unless `query` is specified.
        - name: permissions
          in: query
          type: string
          description: 'A comma separated list of permissions. Permissions can be specified as any:'
          required: true
        - name: issueKey
          in: query
          type: string
          description: The issue key for the issue.
        - name: projectKey
          in: query
          type: string
          description: The project key for the project (case sensitive).
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return per page.
    - name: rest-api-3-user-picker
      path: /rest/api/3/user/picker
      operations:
      - name: atlassianfindusersforpicker
        method: GET
        description: Atlassian Find Users For Picker
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes, such as `displayName`, and `emailAddress`,
            to find relevant users. The string can match the prefix of th
          required: true
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return. The total number of matched users is returned in `total`.
        - name: showAvatar
          in: query
          type: boolean
          description: Include the URI to the user's avatar.
        - name: exclude
          in: query
          type: array
          description: This parameter is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migr
        - name: excludeAccountIds
          in: query
          type: array
          description: A list of account IDs to exclude from the search results. This parameter accepts a comma-separated
            list. Multiple account IDs can also be provided using an ampe
        - name: avatarSize
          in: query
          type: string
        - name: excludeConnectUsers
          in: query
          type: boolean
    - name: rest-api-3-user-search
      path: /rest/api/3/user/search
      operations:
      - name: atlassianfindusers
        method: GET
        description: Atlassian Find Users
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes ( `displayName`, and `emailAddress`) to find
            relevant users. The string can match the prefix of the attri
        - name: username
          in: query
          type: string
        - name: accountId
          in: query
          type: string
          description: A query string that is matched exactly against a user `accountId`. Required, unless `query` or `property`
            is specified.
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of filtered results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return per page.
        - name: property
          in: query
          type: string
          description: 'A query string used to search properties. Property keys are specified by path, so property keys containing
            dot (.) or equals (=) characters cannot be used. The '
    - name: rest-api-3-user-search-query
      path: /rest/api/3/user/search/query
      operations:
      - name: atlassianfindusersbyquery
        method: GET
        description: Atlassian Find Users By Query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: The search query.
          required: true
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return per page.
    - name: rest-api-3-user-search-query-key
      path: /rest/api/3/user/search/query/key
      operations:
      - name: atlassianfinduserkeysbyquery
        method: GET
        description: Atlassian Find User Keys By Query
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: The search query.
          required: true
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResult
          in: query
          type: integer
          description: The maximum number of items to return per page.
    - name: rest-api-3-user-viewissue-search
      path: /rest/api/3/user/viewissue/search
      operations:
      - name: atlassianfinduserswithbrowsepermission
        method: GET
        description: Atlassian Find Users With Browse Permission
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: A query string that is matched against user attributes, such as `displayName` and `emailAddress`, to
            find relevant users. The string can match the prefix of the
        - name: username
          in: query
          type: string
          description: This parameter is no longer available. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migr
        - name: accountId
          in: query
          type: string
          description: A query string that is matched exactly against user `accountId`. Required, unless `query` is specified.
        - name: issueKey
          in: query
          type: string
          description: The issue key for the issue. Required, unless `projectKey` is specified.
        - name: projectKey
          in: query
          type: string
          description: The project key for the project (case sensitive). Required, unless `issueKey` is specified.
        - name: startAt
          in: query
          type: integer
          description: The index of the first item to return in a page of results (page offset).
        - name: maxResults
          in: query
          type: integer
          description: The maximum number of items to return per page.
    authentication:
      type: bearer
      token: '{{env.ATLASSIAN_API_KEY}}'
  exposes:
  - type: rest
    namespace: jira-user-search-rest
    port: 8080
    description: REST adapter for Atlassian The Jira Cloud platform REST API — User Search. One Spectral-compliant resource
      per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/api/3/user/assignable/multiprojectsearch
      name: rest-api-3-user-assignable-multiprojectsearch
      description: REST surface for rest-api-3-user-assignable-multiProjectSearch.
      operations:
      - method: GET
        name: atlassianfindbulkassignableusers
        description: Atlassian Find Users Assignable To Projects
        call: jira-user-search.atlassianfindbulkassignableusers
        with:
          query: rest.query
          username: rest.username
          accountId: rest.accountId
          projectKeys: rest.projectKeys
          startAt: rest.startAt
          maxResults: rest.maxResults
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/assignable/search
      name: rest-api-3-user-assignable-search
      description: REST surface for rest-api-3-user-assignable-search.
      operations:
      - method: GET
        name: atlassianfindassignableusers
        description: Atlassian Find Users Assignable To Issues
        call: jira-user-search.atlassianfindassignableusers
        with:
          query: rest.query
          sessionId: rest.sessionId
          username: rest.username
          accountId: rest.accountId
          project: rest.project
          issueKey: rest.issueKey
          startAt: rest.startAt
          maxResults: rest.maxResults
          actionDescriptorId: rest.actionDescriptorId
          recommend: rest.recommend
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/permission/search
      name: rest-api-3-user-permission-search
      description: REST surface for rest-api-3-user-permission-search.
      operations:
      - method: GET
        name: atlassianfinduserswithallpermissions
        description: Atlassian Find Users With Permissions
        call: jira-user-search.atlassianfinduserswithallpermissions
        with:
          query: rest.query
          username: rest.username
          accountId: rest.accountId
          permissions: rest.permissions
          issueKey: rest.issueKey
          projectKey: rest.projectKey
          startAt: rest.startAt
          maxResults: rest.maxResults
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/picker
      name: rest-api-3-user-picker
      description: REST surface for rest-api-3-user-picker.
      operations:
      - method: GET
        name: atlassianfindusersforpicker
        description: Atlassian Find Users For Picker
        call: jira-user-search.atlassianfindusersforpicker
        with:
          query: rest.query
          maxResults: rest.maxResults
          showAvatar: rest.showAvatar
          exclude: rest.exclude
          excludeAccountIds: rest.excludeAccountIds
          avatarSize: rest.avatarSize
          excludeConnectUsers: rest.excludeConnectUsers
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/search
      name: rest-api-3-user-search
      description: REST surface for rest-api-3-user-search.
      operations:
      - method: GET
        name: atlassianfindusers
        description: Atlassian Find Users
        call: jira-user-search.atlassianfindusers
        with:
          query: rest.query
          username: rest.username
          accountId: rest.accountId
          startAt: rest.startAt
          maxResults: rest.maxResults
          property: rest.property
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/search/query
      name: rest-api-3-user-search-query
      description: REST surface for rest-api-3-user-search-query.
      operations:
      - method: GET
        name: atlassianfindusersbyquery
        description: Atlassian Find Users By Query
        call: jira-user-search.atlassianfindusersbyquery
        with:
          query: rest.query
          startAt: rest.startAt
          maxResults: rest.maxResults
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/search/query/key
      name: rest-api-3-user-search-query-key
      description: REST surface for rest-api-3-user-search-query-key.
      operations:
      - method: GET
        name: atlassianfinduserkeysbyquery
        description: Atlassian Find User Keys By Query
        call: jira-user-search.atlassianfinduserkeysbyquery
        with:
          query: rest.query
          startAt: rest.startAt
          maxResult: rest.maxResult
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/3/user/viewissue/search
      name: rest-api-3-user-viewissue-search
      description: REST surface for rest-api-3-user-viewissue-search.
      operations:
      - method: GET
        name: atlassianfinduserswithbrowsepermission
        description: Atlassian Find Users With Browse Permission
        call: jira-user-search.atlassianfinduserswithbrowsepermission
        with:
          query: rest.query
          username: rest.username
          accountId: rest.accountId
          issueKey: rest.issueKey
          projectKey: rest.projectKey
          startAt: rest.startAt
          maxResults: rest.maxResults
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: jira-user-search-mcp
    port: 9090
    transport: http
    description: MCP adapter for Atlassian The Jira Cloud platform REST API — User Search. One tool per consumed operation,
      routed inline through this capability's consumes block.
    tools:
    - name: atlassian-find-users-assignable-projects
      description: Atlassian Find Users Assignable To Projects
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfindbulkassignableusers
      with:
        query: tools.query
        username: tools.username
        accountId: tools.accountId
        projectKeys: tools.projectKeys
        startAt: tools.startAt
        maxResults: tools.maxResults
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users-assignable-issues
      description: Atlassian Find Users Assignable To Issues
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfindassignableusers
      with:
        query: tools.query
        sessionId: tools.sessionId
        username: tools.username
        accountId: tools.accountId
        project: tools.project
        issueKey: tools.issueKey
        startAt: tools.startAt
        maxResults: tools.maxResults
        actionDescriptorId: tools.actionDescriptorId
        recommend: tools.recommend
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users-permissions
      description: Atlassian Find Users With Permissions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfinduserswithallpermissions
      with:
        query: tools.query
        username: tools.username
        accountId: tools.accountId
        permissions: tools.permissions
        issueKey: tools.issueKey
        projectKey: tools.projectKey
        startAt: tools.startAt
        maxResults: tools.maxResults
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users-picker
      description: Atlassian Find Users For Picker
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfindusersforpicker
      with:
        query: tools.query
        maxResults: tools.maxResults
        showAvatar: tools.showAvatar
        exclude: tools.exclude
        excludeAccountIds: tools.excludeAccountIds
        avatarSize: tools.avatarSize
        excludeConnectUsers: tools.excludeConnectUsers
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users
      description: Atlassian Find Users
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfindusers
      with:
        query: tools.query
        username: tools.username
        accountId: tools.accountId
        startAt: tools.startAt
        maxResults: tools.maxResults
        property: tools.property
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users-query
      description: Atlassian Find Users By Query
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfindusersbyquery
      with:
        query: tools.query
        startAt: tools.startAt
        maxResults: tools.maxResults
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-user-keys-query
      description: Atlassian Find User Keys By Query
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfinduserkeysbyquery
      with:
        query: tools.query
        startAt: tools.startAt
        maxResult: tools.maxResult
      outputParameters:
      - type: object
        mapping: $.
    - name: atlassian-find-users-browse-permission
      description: Atlassian Find Users With Browse Permission
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: jira-user-search.atlassianfinduserswithbrowsepermission
      with:
        query: tools.query
        username: tools.username
        accountId: tools.accountId
        issueKey: tools.issueKey
        projectKey: tools.projectKey
        startAt: tools.startAt
        maxResults: tools.maxResults
      outputParameters:
      - type: object
        mapping: $.