eBay Taxonomy API — Category_tree

naftiko: 1.0.0-alpha2
info:
  label: eBay Taxonomy API — Category_tree
  description: 'eBay Taxonomy API — Category_tree. 8 operations. Lead operation: eBay Get a Category Tree. Self-contained
    Naftiko capability covering one Ebay business surface.'
  tags:
  - Ebay
  - Category_tree
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    EBAY_API_KEY: EBAY_API_KEY
capability:
  consumes:
  - type: http
    namespace: taxonomy-category-tree
    baseUri: https://api.ebay.com{basePath}
    description: eBay Taxonomy API — Category_tree business capability. Self-contained, no shared references.
    resources:
    - name: category_tree-category_tree_id
      path: /category_tree/{category_tree_id}
      operations:
      - name: getcategorytree
        method: GET
        description: eBay Get a Category Tree
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_tree_id
          in: path
          type: string
          description: The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be
            retrieved using the <b>getDefaultCategoryTreeId</b> method.
          required: true
        - name: Accept-Encoding
          in: header
          type: string
          description: 'This header indicates the compression-encoding algorithms the client accepts for the response. This
            value should be set to <code>gzip</code>. <br><br> For more '
    - name: category_tree-category_tree_id-fetch_item_aspects
      path: /category_tree/{category_tree_id}/fetch_item_aspects
      operations:
      - name: fetchitemaspects
        method: GET
        description: eBay Get Aspects for All Leaf Categories in a Marketplace
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_tree_id
          in: path
          type: string
          description: The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be
            retrieved using the <b>getDefaultCategoryTreeId</b> method.
          required: true
    - name: category_tree-category_tree_id-get_category_subtree
      path: /category_tree/{category_tree_id}/get_category_subtree
      operations:
      - name: getcategorysubtree
        method: GET
        description: eBay Get a Category Subtree
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_id
          in: query
          type: string
          description: The unique identifier of the category at the top of the subtree being requested. Metadata on this category
            and all its descendant categories are retrieved.<br><
          required: true
        - name: category_tree_id
          in: path
          type: string
          description: The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be
            retrieved using the <b>getDefaultCategoryTreeId</b> method.
          required: true
        - name: Accept-Encoding
          in: header
          type: string
          description: 'This header indicates the compression-encoding algorithms the client accepts for the response. This
            value should be set to <code>gzip</code>. <br><br> For more '
    - name: category_tree-category_tree_id-get_category_suggestions
      path: /category_tree/{category_tree_id}/get_category_suggestions
      operations:
      - name: getcategorysuggestions
        method: GET
        description: eBay Get Suggested Categories
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_tree_id
          in: path
          type: string
          description: The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be
            retrieved using the <b>getDefaultCategoryTreeId</b> method.
          required: true
        - name: q
          in: query
          type: string
          description: A quoted string that describes or characterizes the item being offered for sale. The string format
            is free form, and can contain any combination of phrases or k
          required: true
    - name: category_tree-category_tree_id-get_compatibility_properties
      path: /category_tree/{category_tree_id}/get_compatibility_properties
      operations:
      - name: getcompatibilityproperties
        method: GET
        description: eBay Get Compatibility Properties
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_tree_id
          in: path
          type: string
          description: This is the unique identifier of category tree. The following is the list of <strong>category_tree_id</strong>
            values and the eBay marketplaces that they repres
          required: true
        - name: category_id
          in: query
          type: string
          description: The unique identifier of an eBay category. This eBay category must be a valid eBay category on the
            specified eBay marketplace, and the category must support par
          required: true
    - name: category_tree-category_tree_id-get_compatibility_property_values
      path: /category_tree/{category_tree_id}/get_compatibility_property_values
      operations:
      - name: getcompatibilitypropertyvalues
        method: GET
        description: eBay Get Compatibility Property Values
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_tree_id
          in: path
          type: string
          description: This is the unique identifier of the category tree. The following is the list of <strong>category_tree_id</strong>
            values and the eBay marketplaces that they re
          required: true
        - name: compatibility_property
          in: query
          type: string
          description: One compatible vehicle property applicable to the specified eBay marketplace and eBay category is specified
            in this required filter. Compatible vehicle properti
          required: true
        - name: category_id
          in: query
          type: string
          description: The unique identifier of an eBay category. This eBay category must be a valid eBay category on the
            specified eBay marketplace, and the category must support par
          required: true
        - name: filter
          in: query
          type: string
          description: One or more compatible vehicle property name/value pairs are passed in through this query parameter.
            The compatible vehicle property name and corresponding valu
    - name: category_tree-category_tree_id-get_item_aspects_for_category
      path: /category_tree/{category_tree_id}/get_item_aspects_for_category
      operations:
      - name: getitemaspectsforcategory
        method: GET
        description: This call returns a list of <i>aspects</i> that are appropriate or necessary for accurately describing
          items in the specified leaf category. Each aspect identifies an item attribute (for example, color,) for which the
          seller will be require
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: category_id
          in: query
          type: string
          description: The unique identifier of the leaf category for which aspects are being requested.<br><br><span class="tablenote">
            <strong>Note:</strong> If the <b>category_id</
          required: true
        - name: category_tree_id
          in: path
          type: string
          description: The unique identifier of the eBay category tree. The category tree ID for an eBay marketplace can be
            retrieved using the <b>getDefaultCategoryTreeId</b> method.
          required: true
    - name: get_default_category_tree_id
      path: /get_default_category_tree_id
      operations:
      - name: getdefaultcategorytreeid
        method: GET
        description: eBay Get a Default Category Tree ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: marketplace_id
          in: query
          type: string
          description: The unique identifier of the eBay marketplace for which the category tree ID is requested. For a list
            of supported marketplace IDs, see <a href="/api-docs/comme
          required: true
    authentication:
      type: bearer
      token: '{{env.EBAY_API_KEY}}'
  exposes:
  - type: rest
    namespace: taxonomy-category-tree-rest
    port: 8080
    description: REST adapter for eBay Taxonomy API — Category_tree. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/category-tree/{category-tree-id}
      name: category-tree-category-tree-id
      description: REST surface for category_tree-category_tree_id.
      operations:
      - method: GET
        name: getcategorytree
        description: eBay Get a Category Tree
        call: taxonomy-category-tree.getcategorytree
        with:
          category_tree_id: rest.category_tree_id
          Accept-Encoding: rest.Accept-Encoding
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/fetch-item-aspects
      name: category-tree-category-tree-id-fetch-item-aspects
      description: REST surface for category_tree-category_tree_id-fetch_item_aspects.
      operations:
      - method: GET
        name: fetchitemaspects
        description: eBay Get Aspects for All Leaf Categories in a Marketplace
        call: taxonomy-category-tree.fetchitemaspects
        with:
          category_tree_id: rest.category_tree_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/get-category-subtree
      name: category-tree-category-tree-id-get-category-subtree
      description: REST surface for category_tree-category_tree_id-get_category_subtree.
      operations:
      - method: GET
        name: getcategorysubtree
        description: eBay Get a Category Subtree
        call: taxonomy-category-tree.getcategorysubtree
        with:
          category_id: rest.category_id
          category_tree_id: rest.category_tree_id
          Accept-Encoding: rest.Accept-Encoding
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/get-category-suggestions
      name: category-tree-category-tree-id-get-category-suggestions
      description: REST surface for category_tree-category_tree_id-get_category_suggestions.
      operations:
      - method: GET
        name: getcategorysuggestions
        description: eBay Get Suggested Categories
        call: taxonomy-category-tree.getcategorysuggestions
        with:
          category_tree_id: rest.category_tree_id
          q: rest.q
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/get-compatibility-properties
      name: category-tree-category-tree-id-get-compatibility-properties
      description: REST surface for category_tree-category_tree_id-get_compatibility_properties.
      operations:
      - method: GET
        name: getcompatibilityproperties
        description: eBay Get Compatibility Properties
        call: taxonomy-category-tree.getcompatibilityproperties
        with:
          category_tree_id: rest.category_tree_id
          category_id: rest.category_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/get-compatibility-property-values
      name: category-tree-category-tree-id-get-compatibility-property-values
      description: REST surface for category_tree-category_tree_id-get_compatibility_property_values.
      operations:
      - method: GET
        name: getcompatibilitypropertyvalues
        description: eBay Get Compatibility Property Values
        call: taxonomy-category-tree.getcompatibilitypropertyvalues
        with:
          category_tree_id: rest.category_tree_id
          compatibility_property: rest.compatibility_property
          category_id: rest.category_id
          filter: rest.filter
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/category-tree/{category-tree-id}/get-item-aspects-for-category
      name: category-tree-category-tree-id-get-item-aspects-for-category
      description: REST surface for category_tree-category_tree_id-get_item_aspects_for_category.
      operations:
      - method: GET
        name: getitemaspectsforcategory
        description: This call returns a list of <i>aspects</i> that are appropriate or necessary for accurately describing
          items in the specified leaf category. Each aspect identifies an item attribute (for example, color,) for which the
          seller will be require
        call: taxonomy-category-tree.getitemaspectsforcategory
        with:
          category_id: rest.category_id
          category_tree_id: rest.category_tree_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/get-default-category-tree-id
      name: get-default-category-tree-id
      description: REST surface for get_default_category_tree_id.
      operations:
      - method: GET
        name: getdefaultcategorytreeid
        description: eBay Get a Default Category Tree ID
        call: taxonomy-category-tree.getdefaultcategorytreeid
        with:
          marketplace_id: rest.marketplace_id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: taxonomy-category-tree-mcp
    port: 9090
    transport: http
    description: MCP adapter for eBay Taxonomy API — Category_tree. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: ebay-get-category-tree
      description: eBay Get a Category Tree
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getcategorytree
      with:
        category_tree_id: tools.category_tree_id
        Accept-Encoding: tools.Accept-Encoding
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-aspects-all-leaf
      description: eBay Get Aspects for All Leaf Categories in a Marketplace
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.fetchitemaspects
      with:
        category_tree_id: tools.category_tree_id
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-category-subtree
      description: eBay Get a Category Subtree
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getcategorysubtree
      with:
        category_id: tools.category_id
        category_tree_id: tools.category_tree_id
        Accept-Encoding: tools.Accept-Encoding
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-suggested-categories
      description: eBay Get Suggested Categories
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getcategorysuggestions
      with:
        category_tree_id: tools.category_tree_id
        q: tools.q
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-compatibility-properties
      description: eBay Get Compatibility Properties
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getcompatibilityproperties
      with:
        category_tree_id: tools.category_tree_id
        category_id: tools.category_id
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-compatibility-property-values
      description: eBay Get Compatibility Property Values
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getcompatibilitypropertyvalues
      with:
        category_tree_id: tools.category_tree_id
        compatibility_property: tools.compatibility_property
        category_id: tools.category_id
        filter: tools.filter
      outputParameters:
      - type: object
        mapping: $.
    - name: this-call-returns-list-i-aspects
      description: This call returns a list of <i>aspects</i> that are appropriate or necessary for accurately describing
        items in the specified leaf category. Each aspect identifies an item attribute (for example, color,) for which the
        seller will be require
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getitemaspectsforcategory
      with:
        category_id: tools.category_id
        category_tree_id: tools.category_tree_id
      outputParameters:
      - type: object
        mapping: $.
    - name: ebay-get-default-category-tree
      description: eBay Get a Default Category Tree ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: taxonomy-category-tree.getdefaultcategorytreeid
      with:
        marketplace_id: tools.marketplace_id
      outputParameters:
      - type: object
        mapping: $.