naftiko: 1.0.0-alpha2
info:
  label: eBay Browse API — Item
  description: 'eBay Browse API — Item. 5 operations. Lead operation: Item. Self-contained Naftiko capability covering one
    Ebay business surface.'
  tags:
  - Ebay
  - Item
  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
    baseUri: https://api.ebay.com{basePath}
    description: eBay Browse API — Item business capability. Self-contained, no shared references.
    resources:
    - name: item
      path: /item/
      operations:
      - name: getitems
        method: GET
        description: This method retrieves the details about specific items that buyers need to make a purchasing decision.<br><br><span
          class="tablenote"><b>Note:</b> This is a <a href="/api-docs/static/versioning.html#limited " target="_blank"><img
          src="/cms/
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: item_ids
          in: query
          type: string
          description: A comma separated list of the unique identifiers of the items to retrieve (maximum 20).<br><br><span
            class="tablenote"><b>Note:</b> In any given request, either
        - name: item_group_ids
          in: query
          type: string
          description: A comma separated list of the unique identifiers of the item groups being retrieved (maximum 10).<br><br><span
            class="tablenote"><b>Note:</b> In any given reque
        - 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-get_item_by_legacy_id
      path: /item/get_item_by_legacy_id
      operations:
      - name: getitembylegacyid
        method: GET
        description: 'This method is a bridge between the eBay legacy APIs, such as <b>Shopping</b> and <b>Finding</b>, and
          the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item"
          and what the item ID '
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fieldgroups
          in: query
          type: string
          description: This field controls what is returned in the response. If this field is not set, the method returns
            all details about the item. Multiple <code>fieldgroups</code>
        - name: legacy_item_id
          in: query
          type: string
          description: This query parameter is the unique identifier that specifies the item being retrieved.<br><br><span
            class="tablenote"><b> Note:</b> When passing in the ID for a
          required: true
        - name: legacy_variation_id
          in: query
          type: string
          description: This query parameter specifies the legacy item ID of a specific item in a multi-variation listing,
            such as that for the <i>red shirt size L</i> item.<br><br><di
        - name: legacy_variation_sku
          in: query
          type: string
          description: This query parameter specifies the legacy SKU of an item. SKUs are the unique identifiers of an item
            created by the seller.<br><br>The following is an example o
        - 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-get_items_by_item_group
      path: /item/get_items_by_item_group
      operations:
      - name: getitemsbyitemgroup
        method: GET
        description: This method retrieves details about individual items in an item group. An item group is an item that
          has various aspect differences, such as color, size, storage capacity, etc.<br><br>You pass in the <b>item_group_id</b>
          as a URI parameter.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fieldgroups
          in: query
          type: string
          description: This field controls what is returned in the response. If this field is not set, the method returns
            all details about the item.<br><br><b>Valid Values:</b><br><b
        - name: item_group_id
          in: query
          type: string
          description: 'This query parameter specifies the unique identifier of an item group for which information is to
            be returned. An item group is an item that has various aspect '
          required: true
        - 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-item_id
      path: /item/{item_id}
      operations:
      - name: getitem
        method: GET
        description: This method retrieves the details of a specific item, such as description, price, category, all item
          aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery,
          and other information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fieldgroups
          in: query
          type: string
          description: This parameter controls what is returned in the response. If this field is not set, the method returns
            all the details of the item.<br><br><span class="tablenot
        - name: item_id
          in: path
          type: string
          description: 'This path parameter specifies the unique RESTful identifier of the item being retrieved. <br><br><b>RESTful
            Item ID Format: </b><code>v1</code>|<code><i>#</i></'
          required: true
        - 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-item_id-check_compatibility
      path: /item/{item_id}/check_compatibility
      operations:
      - name: checkcompatibility
        method: POST
        description: This method checks if a product is compatible with the specified item. You can use this method to check
          the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.<br><br>For example, to check
          the compatibility o
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: item_id
          in: path
          type: string
          description: 'This path parameter specifies the unique RESTful identifier of an item (such as the park you want
            to check).<br><br><b>RESTful Item ID Format: </b><code>v1</cod'
          required: true
        - 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.<br><br>Its value should
            be set to <code>application/json</code>.<br><br>For more in
          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-rest
    port: 8080
    description: REST adapter for eBay Browse API — Item. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/item
      name: item
      description: REST surface for item.
      operations:
      - method: GET
        name: getitems
        description: This method retrieves the details about specific items that buyers need to make a purchasing decision.<br><br><span
          class="tablenote"><b>Note:</b> This is a <a href="/api-docs/static/versioning.html#limited " target="_blank"><img
          src="/cms/
        call: browse-item.getitems
        with:
          item_ids: rest.item_ids
          item_group_ids: rest.item_group_ids
          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/get-item-by-legacy-id
      name: item-get-item-by-legacy-id
      description: REST surface for item-get_item_by_legacy_id.
      operations:
      - method: GET
        name: getitembylegacyid
        description: 'This method is a bridge between the eBay legacy APIs, such as <b>Shopping</b> and <b>Finding</b>, and
          the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item"
          and what the item ID '
        call: browse-item.getitembylegacyid
        with:
          fieldgroups: rest.fieldgroups
          legacy_item_id: rest.legacy_item_id
          legacy_variation_id: rest.legacy_variation_id
          legacy_variation_sku: rest.legacy_variation_sku
          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/get-items-by-item-group
      name: item-get-items-by-item-group
      description: REST surface for item-get_items_by_item_group.
      operations:
      - method: GET
        name: getitemsbyitemgroup
        description: This method retrieves details about individual items in an item group. An item group is an item that
          has various aspect differences, such as color, size, storage capacity, etc.<br><br>You pass in the <b>item_group_id</b>
          as a URI parameter.
        call: browse-item.getitemsbyitemgroup
        with:
          fieldgroups: rest.fieldgroups
          item_group_id: rest.item_group_id
          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/{item-id}
      name: item-item-id
      description: REST surface for item-item_id.
      operations:
      - method: GET
        name: getitem
        description: This method retrieves the details of a specific item, such as description, price, category, all item
          aspects, condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery,
          and other information
        call: browse-item.getitem
        with:
          fieldgroups: rest.fieldgroups
          item_id: rest.item_id
          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/{item-id}/check-compatibility
      name: item-item-id-check-compatibility
      description: REST surface for item-item_id-check_compatibility.
      operations:
      - method: POST
        name: checkcompatibility
        description: This method checks if a product is compatible with the specified item. You can use this method to check
          the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.<br><br>For example, to check
          the compatibility o
        call: browse-item.checkcompatibility
        with:
          item_id: rest.item_id
          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-mcp
    port: 9090
    transport: http
    description: MCP adapter for eBay Browse API — Item. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: this-method-retrieves-details-about
      description: This method retrieves the details about specific items that buyers need to make a purchasing decision.<br><br><span
        class="tablenote"><b>Note:</b> This is a <a href="/api-docs/static/versioning.html#limited " target="_blank"><img
        src="/cms/
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: browse-item.getitems
      with:
        item_ids: tools.item_ids
        item_group_ids: tools.item_group_ids
        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: this-method-is-bridge-between
      description: 'This method is a bridge between the eBay legacy APIs, such as <b>Shopping</b> and <b>Finding</b>, and
        the eBay Buy APIs. There are differences between how legacy APIs and RESTful APIs return the identifier of an "item"
        and what the item ID '
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: browse-item.getitembylegacyid
      with:
        fieldgroups: tools.fieldgroups
        legacy_item_id: tools.legacy_item_id
        legacy_variation_id: tools.legacy_variation_id
        legacy_variation_sku: tools.legacy_variation_sku
        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: this-method-retrieves-details-about-2
      description: This method retrieves details about individual items in an item group. An item group is an item that has
        various aspect differences, such as color, size, storage capacity, etc.<br><br>You pass in the <b>item_group_id</b>
        as a URI parameter.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: browse-item.getitemsbyitemgroup
      with:
        fieldgroups: tools.fieldgroups
        item_group_id: tools.item_group_id
        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: this-method-retrieves-details-specific
      description: This method retrieves the details of a specific item, such as description, price, category, all item aspects,
        condition, return policies, seller feedback and score, shipping options, shipping costs, estimated delivery, and other
        information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: browse-item.getitem
      with:
        fieldgroups: tools.fieldgroups
        item_id: tools.item_id
        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: this-method-checks-if-product
      description: This method checks if a product is compatible with the specified item. You can use this method to check
        the compatibility of cars, trucks, and motorcycles with a specific part listed on eBay.<br><br>For example, to check
        the compatibility o
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: browse-item.checkcompatibility
      with:
        item_id: tools.item_id
        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: $.