Pipedrive API v2 — ItemSearch

naftiko: 1.0.0-alpha2
info:
  label: Pipedrive API v2 — ItemSearch
  description: 'Pipedrive API v2 — ItemSearch. 2 operations. Lead operation: Perform a search from multiple item types. Self-contained
    Naftiko capability covering one Pipedrive business surface.'
  tags:
  - Pipedrive
  - ItemSearch
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    PIPEDRIVE_API_KEY: PIPEDRIVE_API_KEY
capability:
  consumes:
  - type: http
    namespace: v2-itemsearch
    baseUri: https://api.pipedrive.com/api/v2
    description: Pipedrive API v2 — ItemSearch business capability. Self-contained, no shared references.
    resources:
    - name: itemSearch
      path: /itemSearch
      operations:
      - name: searchitem
        method: GET
        description: Perform a search from multiple item types
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: term
          in: query
          type: string
          description: The search term to look for. Minimum 2 characters (or 1 if using `exact_match`). Please note that the
            search term has to be URL encoded.
          required: true
        - name: item_types
          in: query
          type: string
          description: A comma-separated string array. The type of items to perform the search from. Defaults to all.
        - name: fields
          in: query
          type: string
          description: A comma-separated string array. The fields to perform the search from. Defaults to all. Relevant for
            each item type are:<br> <table> <tr><th><b>Item type</b></t
        - name: search_for_related_items
          in: query
          type: boolean
          description: 'When enabled, the response will include up to 100 newest related leads and 100 newest related deals
            for each found person and organization and up to 100 newest '
        - name: exact_match
          in: query
          type: boolean
          description: When enabled, only full exact matches against the given term are returned. It is <b>not</b> case sensitive.
        - name: include_fields
          in: query
          type: string
          description: A comma-separated string array. Supports including optional fields in the results which are not provided
            by default.
        - name: limit
          in: query
          type: integer
          description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please
            note that a maximum value of 100 is allowed.
        - name: cursor
          in: query
          type: string
          description: For pagination, the marker (an opaque string value) representing the first item on the next page
    - name: itemSearch-field
      path: /itemSearch/field
      operations:
      - name: searchitembyfield
        method: GET
        description: Perform a search using a specific field from an item type
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: term
          in: query
          type: string
          description: The search term to look for. Minimum 2 characters (or 1 if `match` is `exact`). Please note that the
            search term has to be URL encoded.
          required: true
        - name: entity_type
          in: query
          type: string
          description: The type of the field to perform the search from
          required: true
        - name: match
          in: query
          type: string
          description: The type of match used against the term. The search <b>is</b> case sensitive.<br/><br/> E.g. in case
            of searching for a value `monkey`, <ul> <li>with `exact` ma
        - name: field
          in: query
          type: string
          description: The key of the field to search from. The field key can be obtained by fetching the list of the fields
            using any of the fields' API GET methods (dealFields, pers
          required: true
        - name: limit
          in: query
          type: integer
          description: For pagination, the limit of entries to be returned. If not provided, 100 items will be returned. Please
            note that a maximum value of 500 is allowed.
        - name: cursor
          in: query
          type: string
          description: For pagination, the marker (an opaque string value) representing the first item on the next page
    authentication:
      type: bearer
      token: '{{env.PIPEDRIVE_API_KEY}}'
  exposes:
  - type: rest
    namespace: v2-itemsearch-rest
    port: 8080
    description: REST adapter for Pipedrive API v2 — ItemSearch. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/itemsearch
      name: itemsearch
      description: REST surface for itemSearch.
      operations:
      - method: GET
        name: searchitem
        description: Perform a search from multiple item types
        call: v2-itemsearch.searchitem
        with:
          term: rest.term
          item_types: rest.item_types
          fields: rest.fields
          search_for_related_items: rest.search_for_related_items
          exact_match: rest.exact_match
          include_fields: rest.include_fields
          limit: rest.limit
          cursor: rest.cursor
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/itemsearch/field
      name: itemsearch-field
      description: REST surface for itemSearch-field.
      operations:
      - method: GET
        name: searchitembyfield
        description: Perform a search using a specific field from an item type
        call: v2-itemsearch.searchitembyfield
        with:
          term: rest.term
          entity_type: rest.entity_type
          match: rest.match
          field: rest.field
          limit: rest.limit
          cursor: rest.cursor
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: v2-itemsearch-mcp
    port: 9090
    transport: http
    description: MCP adapter for Pipedrive API v2 — ItemSearch. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: perform-search-multiple-item-types
      description: Perform a search from multiple item types
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v2-itemsearch.searchitem
      with:
        term: tools.term
        item_types: tools.item_types
        fields: tools.fields
        search_for_related_items: tools.search_for_related_items
        exact_match: tools.exact_match
        include_fields: tools.include_fields
        limit: tools.limit
        cursor: tools.cursor
      outputParameters:
      - type: object
        mapping: $.
    - name: perform-search-using-specific-field
      description: Perform a search using a specific field from an item type
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: v2-itemsearch.searchitembyfield
      with:
        term: tools.term
        entity_type: tools.entity_type
        match: tools.match
        field: tools.field
        limit: tools.limit
        cursor: tools.cursor
      outputParameters:
      - type: object
        mapping: $.