eBay Browse API — Item_summary

naftiko: 1.0.0-alpha2
info:
  label: eBay Browse API — Item_summary
  description: 'eBay Browse API — Item_summary. 2 operations. Lead operation: Item_summary. Self-contained Naftiko capability
    covering one Ebay business surface.'
  tags:
  - Ebay
  - Item_summary
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    EBAY_API_KEY: EBAY_API_KEY
capability:
  consumes:
  - type: http
    namespace: browse-item-summary
    baseUri: https://api.ebay.com{basePath}
    description: eBay Browse API — Item_summary business capability. Self-contained, no shared references.
    resources:
    - name: item_summary-search
      path: /item_summary/search
      operations:
      - name: search
        method: GET
        description: This method searches for eBay items by various query parameters and retrieves summaries of the items.
          You can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.<br><br><span
          class="tablenote
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: aspect_filter
          in: query
          type: string
          description: This field lets you filter by item aspects. The aspect name/value pairs and category, which is required,
            is used to limit the results to specific aspects of the
        - name: auto_correct
          in: query
          type: string
          description: A query parameter that enables auto correction.<br><br>A sample is shown below:<pre>/buy/browse/v1/item_summary/search?auto_correct=KEYWORD</pre><span
            class="ta
        - name: category_ids
          in: query
          type: string
          description: <a name="category_ids"></a>The category ID is used to limit the results that are returned. This field
            may pass in one category ID or a comma separated list of I
        - name: charity_ids
          in: query
          type: string
          description: The charity ID filters results to return only those items associated with the specified charity.<br><br><span
            class="tablenote"><b>Note:</b> <code>charity_ids</
        - name: compatibility_filter
          in: query
          type: string
          description: This field specifies the attributes used to define a specific product. The service searches for items
            matching the keyword, or matching the keyword and a produc
        - name: epid
          in: query
          type: string
          description: The ePID is the eBay product identifier of a product from the eBay product catalog. This field limits
            the results to only items in the specified ePID.<br><br>Us
        - name: fieldgroups
          in: query
          type: string
          description: 'A comma-separated list of values that controls what is returned in the response. The default is <code>MATCHING_ITEMS</code>,
            which returns the items that match '
        - name: filter
          in: query
          type: string
          description: An array of field filters that can be used to limit/customize the result set.<br><br>Refer to <a href="/api-docs/buy/static/ref-buy-browse-filters.html"
            target=
        - name: gtin
          in: query
          type: string
          description: This field lets you search by the Global Trade Item Number of an item as defined by <a href="https://www.gtin.info
            " target="_blank">https://www.gtin.info</a>.<
        - name: limit
          in: query
          type: string
          description: The number of items from the result set returned in a single page.<br><br><span class="tablenote"><b>Note:</b>
            If a value is set in the <code>limit</code> field
        - name: offset
          in: query
          type: string
          description: Specifies the number of items to skip in the result set. This is used with the <code>limit</code> field
            to control the pagination of the output.<br><br>For exam
        - name: q
          in: query
          type: string
          description: 'A string consisting of one or more keywords used to search for items on eBay.<br><br><span class="tablenote"><b>Note:</b>
            The <code>*</code> wildcard character '
        - name: sort
          in: query
          type: string
          description: Specifies the criteria on which returned items are to be sorted.<br><br>Items can be sorted in ascending
            order based on:<ul><li>Price (<code>sort=price</code>)<
        - name: X-EBAY-C-ENDUSERCTX
          in: header
          type: string
          description: This header is required to support revenue sharing for eBay Partner Network and to improve the accuracy
            of shipping and delivery time estimations.<br><br>For ad
        - name: X-EBAY-C-MARKETPLACE-ID
          in: header
          type: string
          description: This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of
            the US.<br><br><span class="tablenote"><b>Note:</b> If a ma
        - name: Accept-Language
          in: header
          type: string
          description: This header is used to indicate the natural language and locale preferred by the user for the response.<br><br>This
            header is required when targeting a specific
    - name: item_summary-search_by_image
      path: /item_summary/search_by_image
      operations:
      - name: searchbyimage
        method: POST
        description: <span class="tablenote"><b>Note:</b> <img src="/cms/img/docs/experimental-icon.svg" class="legend-icon
          experimental-icon" alt="Experimental Method" title="Experimental Method"> This is an <a href="/api-docs/static/versioning.html#experiment
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: aspect_filter
          in: query
          type: string
          description: This field lets you filter by item aspects. The aspect name/value pairs and category, which is required,
            is used to limit the results to specific aspects of the
        - name: category_ids
          in: query
          type: string
          description: </a>The category ID is used to limit the results that are returned. This field may pass in one category
            ID or a comma separated list of IDs as illustrated in th
        - name: charity_ids
          in: query
          type: string
          description: The charity ID filters results to return only those items associated with the specified charity.<br><br><span
            class="tablenote"><b>Note:</b> <code>charity_ids</
        - name: fieldgroups
          in: query
          type: string
          description: 'A comma-separated list of values that controls what is returned in the response. The default is <code>MATCHING_ITEMS</code>,
            which returns the items that match '
        - name: filter
          in: query
          type: string
          description: An array of field filters that can be used to limit/customize the result set.<br><br>Refer to <a href="/api-docs/buy/static/ref-buy-browse-filters.html"
            target=
        - name: limit
          in: query
          type: string
          description: The number of items from the result set returned in a single page.<br><br><span class="tablenote"><b>Note:</b>
            If a value is set in the <code>limit</code> field
        - name: offset
          in: query
          type: string
          description: Specifies the number of items to skip in the result set. This is used with the <code>limit</code> field
            to control the pagination of the output.<br><br>For exam
        - name: sort
          in: query
          type: string
          description: '<span class="tablenote"><b>Note:</b> This call currently returns results in a best-match order. This
            query parameter presently has no practical use.</span> For '
        - name: X-EBAY-C-ENDUSERCTX
          in: header
          type: string
          description: This header is required to support revenue sharing for eBay Partner Network and to improve the accuracy
            of shipping and delivery time estimations.<br><br>For ad
        - name: X-EBAY-C-MARKETPLACE-ID
          in: header
          type: string
          description: This header identifies the seller's eBay marketplace. It is required for all marketplaces outside of
            the US.<br><br><span class="tablenote"><b>Note:</b> If a ma
        - name: Content-Type
          in: header
          type: string
          description: This header indicates the format of the request body provided by the client. Its value should be set
            to <code>application/json</code>.<br><br>For more informati
          required: true
        - name: Accept-Language
          in: header
          type: string
          description: This header is used to indicate the natural language and locale preferred by the user for the response.<br><br>This
            header is required when targeting a specific
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    authentication:
      type: bearer
      token: '{{env.EBAY_API_KEY}}'
  exposes:
  - type: rest
    namespace: browse-item-summary-rest
    port: 8080
    description: REST adapter for eBay Browse API — Item_summary. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/item-summary/search
      name: item-summary-search
      description: REST surface for item_summary-search.
      operations:
      - method: GET
        name: search
        description: This method searches for eBay items by various query parameters and retrieves summaries of the items.
          You can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.<br><br><span
          class="tablenote
        call: browse-item-summary.search
        with:
          aspect_filter: rest.aspect_filter
          auto_correct: rest.auto_correct
          category_ids: rest.category_ids
          charity_ids: rest.charity_ids
          compatibility_filter: rest.compatibility_filter
          epid: rest.epid
          fieldgroups: rest.fieldgroups
          filter: rest.filter
          gtin: rest.gtin
          limit: rest.limit
          offset: rest.offset
          q: rest.q
          sort: rest.sort
          X-EBAY-C-ENDUSERCTX: rest.X-EBAY-C-ENDUSERCTX
          X-EBAY-C-MARKETPLACE-ID: rest.X-EBAY-C-MARKETPLACE-ID
          Accept-Language: rest.Accept-Language
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/item-summary/search-by-image
      name: item-summary-search-by-image
      description: REST surface for item_summary-search_by_image.
      operations:
      - method: POST
        name: searchbyimage
        description: <span class="tablenote"><b>Note:</b> <img src="/cms/img/docs/experimental-icon.svg" class="legend-icon
          experimental-icon" alt="Experimental Method" title="Experimental Method"> This is an <a href="/api-docs/static/versioning.html#experiment
        call: browse-item-summary.searchbyimage
        with:
          aspect_filter: rest.aspect_filter
          category_ids: rest.category_ids
          charity_ids: rest.charity_ids
          fieldgroups: rest.fieldgroups
          filter: rest.filter
          limit: rest.limit
          offset: rest.offset
          sort: rest.sort
          X-EBAY-C-ENDUSERCTX: rest.X-EBAY-C-ENDUSERCTX
          X-EBAY-C-MARKETPLACE-ID: rest.X-EBAY-C-MARKETPLACE-ID
          Content-Type: rest.Content-Type
          Accept-Language: rest.Accept-Language
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: browse-item-summary-mcp
    port: 9090
    transport: http
    description: MCP adapter for eBay Browse API — Item_summary. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: this-method-searches-ebay-items
      description: This method searches for eBay items by various query parameters and retrieves summaries of the items. You
        can search by keyword, category, eBay product ID (ePID), or GTIN, charity ID, or a combination of these.<br><br><span
        class="tablenote
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: browse-item-summary.search
      with:
        aspect_filter: tools.aspect_filter
        auto_correct: tools.auto_correct
        category_ids: tools.category_ids
        charity_ids: tools.charity_ids
        compatibility_filter: tools.compatibility_filter
        epid: tools.epid
        fieldgroups: tools.fieldgroups
        filter: tools.filter
        gtin: tools.gtin
        limit: tools.limit
        offset: tools.offset
        q: tools.q
        sort: tools.sort
        X-EBAY-C-ENDUSERCTX: tools.X-EBAY-C-ENDUSERCTX
        X-EBAY-C-MARKETPLACE-ID: tools.X-EBAY-C-MARKETPLACE-ID
        Accept-Language: tools.Accept-Language
      outputParameters:
      - type: object
        mapping: $.
    - name: span-class-tablenote-b-note-b-img-src
      description: <span class="tablenote"><b>Note:</b> <img src="/cms/img/docs/experimental-icon.svg" class="legend-icon
        experimental-icon" alt="Experimental Method" title="Experimental Method"> This is an <a href="/api-docs/static/versioning.html#experiment
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: browse-item-summary.searchbyimage
      with:
        aspect_filter: tools.aspect_filter
        category_ids: tools.category_ids
        charity_ids: tools.charity_ids
        fieldgroups: tools.fieldgroups
        filter: tools.filter
        limit: tools.limit
        offset: tools.offset
        sort: tools.sort
        X-EBAY-C-ENDUSERCTX: tools.X-EBAY-C-ENDUSERCTX
        X-EBAY-C-MARKETPLACE-ID: tools.X-EBAY-C-MARKETPLACE-ID
        Content-Type: tools.Content-Type
        Accept-Language: tools.Accept-Language
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.