> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Categories

> This endpoint is used to search and find specific categories based on the search criteria given in the request body. This endpoint is also used to find the root category that's automatically created when the merchant is onboarded to fabric **Product Catalog**.



## OpenAPI

````yaml category.openapi post /categories/search
openapi: 3.0.0
info:
  title: Products - Categories API
  description: >-
    Categories (also called hierarchies or nodes) form a hierarchical tree
    structure to organize items and services into intuitive groups. Organizing
    items this way simplifies item discovery on your e-commerce platform
    (website or app). **Categories** is the original tree of Product List with
    nested levels of categories. Each item is placed where it belongs within a
    category. For example, `Computers` is a parent category with `Laptops` and
    `Desktops` as children categories, and `MacBook Pro` is an item within
    `Laptops`. This organization can be represented as Computers -> Laptops ->
    MacBook Pro. **Collections** serve as alternative organizations of Category
    system, which is the original, single source for all items and categories.
    Their main purpose is distribution management by displaying items on your
    e-commerce platform based on browsing structures you need to achieve various
    merchandising objectives, such as organizational requirements,
    multi-regional assortments, multi-channel assortments, and collections. For
    example, a company that sells, repairs, and supports computers and related
    items and services will have a Category system with a complete list of SKUs.
    Because Category system isn't granular enough to be used on Storefront,
    multiple Collections are created to target specific shopper segment
    experiences. For laptop consumers, you might have one collection that lists
    all the laptops and PCs. For large businesses, you will have another
    collection that lists all commercial laptops, PCs, printers, and servers.
    Both of the collections will act as filters of the Category, tailored to the
    purpose of a merchandising strategy.
  version: 3.0.0
  x-audience: external-public
  contact:
    email: support@fabric.inc
    name: Product team
  license:
    name: fabric API License
    url: https://fabric.inc/api-license
  termsOfService: https://fabric.inc/terms-of-use
servers:
  - url: https://api.fabric.inc/v3
    description: Production URL
security:
  - authorization: []
tags:
  - name: Categories
    description: >-
      Categories are organized into a hierarchical tree structure based on
      common attributes, allowing logical grouping of items. The Categories
      endpoints enables CRUD operations, such as creating, locating, and
      managing categories.
  - name: Collections
    description: >-
      As the **Categories** system may not be sufficiently granular to
      accommodate all Storefront use cases, **Collections** provide an
      alternative means of organizing products on the Storefront. Collections
      create a representational categorization of products, and are primarily
      used by merchants for short-term marketing campaigns. For instance, a
      collection could be created for a New Year sale that highlights discounted
      furniture products.
  - name: Navigation Paths
    description: >-
      Paths indicate the navigation of the current category or collection to its
      root category or collection. These navigation paths are helpful in
      determining the exact position of a category or collection within the
      hierarchical tree structure.
  - name: Bulk action for categories and collections
    description: These endpoints support creating and updating categories and collections.
externalDocs:
  description: Find out more about Products (previously called PIM)
  url: https://developer.fabric.inc/docs/products-overview
paths:
  /categories/search:
    post:
      tags:
        - Categories
      summary: Find Categories
      description: >-
        This endpoint is used to search and find specific categories based on
        the search criteria given in the request body. This endpoint is also
        used to find the root category that's automatically created when the
        merchant is onboarded to fabric **Product Catalog**.
      operationId: searchCategory
      parameters:
        - $ref: '#/components/parameters/x-fabric-tenant-id'
        - $ref: '#/components/parameters/x-fabric-request-id'
      requestBody:
        $ref: '#/components/requestBodies/searchCategoryRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/searchCategoryResponse'
          headers:
            x-fabric-request-id:
              $ref: '#/components/headers/x-fabric-request-id-header'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/notAuthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '413':
          $ref: '#/components/responses/payloadLimitExceededError'
        '500':
          $ref: '#/components/responses/internalServerError'
components:
  parameters:
    x-fabric-tenant-id:
      name: x-fabric-tenant-id
      in: header
      description: >-
        A header used by fabric to identify the tenant making the request. You
        must include tenant id in the authentication header for an API request
        to access any of fabric’s endpoints. You can retrieve the tenant id ,
        which is also called account id, from
        [Copilot](/v3/platform/settings/account-details/getting-the-account-id).
        This header is required.
      schema:
        type: string
        example: 517fa9dfd42d8b00g1o3k312
    x-fabric-request-id:
      name: x-fabric-request-id
      in: header
      description: Unique request ID
      schema:
        type: string
        example: 263e731c-45c8-11ed-b878-0242ac120002
      required: false
  requestBodies:
    searchCategoryRequest:
      description: Request body for attribute creation
      content:
        application/json:
          schema:
            type: object
            required:
              - match
            additionalProperties: false
            properties:
              sort:
                type: string
                description: >-
                  Sorting criteria. Supported values are `createdAt`,
                  `updatedAt`, and `name`. `-` refers to descending and `+`
                  refers to ascending order
                example: +name,-createdAt
              match:
                description: Specification for matching attributes
                type: object
                minProperties: 1
                properties:
                  id:
                    $ref: '#/components/schemas/simpleStringSearchOperation'
                  name:
                    allOf:
                      - $ref: '#/components/schemas/stringSearchOperation'
                    type: object
                    description: >-
                      Searches for attributes that matches the query. Append
                      locale and name with a `#` as a value
                    properties:
                      locale:
                        type: array
                        description: >-
                          If `isLocalizable` is true, searches for the requested
                          name in the list of locales provided here. If
                          `isLocalizable` is false, searches for the
                          non-localized names.
                        items:
                          type: string
                          description: Locale
                          example: en_US
                  isLocalizable:
                    $ref: '#/components/schemas/booleanSearchOperation'
                  isRoot:
                    $ref: '#/components/schemas/booleanSearchOperation'
                  isLeaf:
                    $ref: '#/components/schemas/booleanSearchOperation'
                  attribute:
                    type: array
                    items:
                      $ref: '#/components/schemas/attributeSearchOperation'
                  productAttributeIds:
                    $ref: '#/components/schemas/simpleStringSearchOperation'
                  hasProductAttributeMandatory:
                    $ref: '#/components/schemas/booleanSearchOperation'
                    deprecated: true
                  updatedBy:
                    $ref: '#/components/schemas/simpleStringSearchOperation'
                  createdAt:
                    $ref: '#/components/schemas/datetimeSearchOperation'
                  updatedAt:
                    $ref: '#/components/schemas/datetimeSearchOperation'
              offset:
                description: >-
                  Number of records to skip before returning records. For
                  example, `offset=20, limit=10` returns records 21-30.
                type: integer
                format: int32
                default: 0
                example: 2
              limit:
                type: integer
                format: int32
                default: 10
                example: 10
                description: Maximum number of records per page
  schemas:
    searchCategoryResponse:
      description: Search categories response
      allOf:
        - $ref: '#/components/schemas/paginatedResultMeta'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/categoryResponse'
    simpleStringSearchOperation:
      type: object
      description: Simple string search
      anyOf:
        - $ref: '#/components/schemas/simpleMultiStringSearchOperation'
        - $ref: '#/components/schemas/simpleSingleStringSearchOperation'
    stringSearchOperation:
      type: object
      description: String search
      anyOf:
        - $ref: '#/components/schemas/simpleMultiStringSearchOperation'
        - $ref: '#/components/schemas/singleStringSearchOperation'
    booleanSearchOperation:
      type: object
      description: Boolean search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a `boolean` type
          example: EQUALS
          enum:
            - EQUALS
        value:
          $ref: '#/components/schemas/booleanSchema'
    attributeSearchOperation:
      type: object
      description: >-
        Attributes are searched in combination of `id` and `value`. Search can
        be performed on an array of attribute ID and attribute value pair.
      properties:
        id:
          type: string
          description: 24-character system-generated attribute ID
          example: 60184766610c0e32a86d8758
        value:
          type: array
          description: Attribute value
          items:
            $ref: '#/components/schemas/attributeValueInfo'
    datetimeSearchOperation:
      type: object
      description: Date-time search
      anyOf:
        - $ref: '#/components/schemas/datetimeRangeOperation'
        - $ref: '#/components/schemas/datetimeInOperation'
        - $ref: '#/components/schemas/datetimeOperation'
    paginatedResultMeta:
      description: Meta details needed for every paginated response
      type: object
      properties:
        offset:
          type: integer
          format: int32
          default: 0
          example: 5
          description: >-
            Number of records to skip before returning records. For example,
            `offset=20, limit=10` returns records 21-30.
        limit:
          type: integer
          format: int32
          default: 10
          example: 10
          description: Maximum number of records per page
        count:
          type: integer
          format: int32
          example: 100
          description: Total number of records in the response
    categoryResponse:
      type: object
      description: Category details
      properties:
        id:
          type: string
          description: 24-character system-generated category ID
          example: 53184766610c0e32a86d875
        name:
          type: string
          example: Color
          description: Non-localized category name
        localizedProperties:
          description: Localized properties of category
          allOf:
            - $ref: '#/components/schemas/localizedProperties'
        isLocalizable:
          type: boolean
          example: true
          description: >-
            true: Category name is translated into different languages or
            localized for different regions <br /> false: Category name isn't
            localized **Note**: Refer to `localizedProperties` to get relevant
            details based on locale
        isRoot:
          type: boolean
          example: true
          description: >-
            true: This is a root category <br /> false: This isn't a root
            category
        isLeaf:
          type: boolean
          example: false
          description: >-
            true: This is the last category of the branch with no further
            children categories <br /> false: This isn't the last category of
            the branch and has children categories
        hasProducts:
          type: boolean
          description: >-
            true: This is the leaf category of the branch which has some
            products in it <br /> false: This branch doesn't have any direct
            products assigned to it
          example: true
        categoryAttributes:
          description: Attributes assigned to the specified category
          type: array
          items:
            $ref: '#/components/schemas/attribute'
        productAttributes:
          type: array
          description: Attributes assigned for all products in the specified category.
          items:
            type: object
            properties:
              id:
                type: string
                example: 33184766610c0e32a86d8759
                description: 24-character system-generated attribute ID
              name:
                type: string
                example: Color
                description: Non-localized attribute name
              localizedProperties:
                allOf:
                  - description: Localized properties of attribute
                  - $ref: '#/components/schemas/localizedProperties'
              isLocalizable:
                type: boolean
                example: true
                description: >-
                  true: Attribute name is translated into different languages or
                  localized for different regions <br /> false: Attribute name
                  isn't localized **Note**: Refer to `localizedProperties` to
                  get relevant attributes based on locale
              isInherited:
                type: boolean
                example: true
                description: >-
                  true: Attribute is inherited from its parent. <br /> false:
                  Attribute isn't inherited from parent
              type:
                type: string
                example: TEXT
                description: Attribute type
              isMandatory:
                type: boolean
                description: 'true: Attribute is mandatory <br /> Attribute is optional'
                example: true
        productIds:
          type: array
          items:
            type: string
            description: >-
              System-generated 24-character product IDs associated with a
              category
            example: 64184766610c0e32a86d8758
        children:
          type: array
          description: Immediate children of the specified category
          items:
            type: object
            properties:
              id:
                type: string
                example: 33184766610c0e32a86d8759
                description: 24-character system-generated ID of child category
              name:
                type: string
                example: Color
                description: Non-localized name of child category
              localizedProperties:
                allOf:
                  - description: Localized properties of child category
                  - $ref: '#/components/schemas/localizedProperties'
              isLocalizable:
                type: boolean
                example: true
                description: >-
                  true: Category name is translated into different languages or
                  localized for different regions <br /> false: Category name
                  isn't localized **Note**: Refer to `localizedProperties` to
                  get relevant details based on locale
              isLeaf:
                type: boolean
                example: false
                description: >-
                  true: This is the last category of the branch with no further
                  children categories <br /> false: This isn't the last category
                  of the branch and has children categories
              hasProducts:
                type: boolean
                description: >-
                  true: This is the leaf category of the branch which has some
                  products in it <br /> false: This branch doesn't have any
                  direct products assigned to it
                example: true
        updatedBy:
          type: string
          example: test@eamil.com
          description: Email of user who last update the category
        updatedAt:
          type: string
          example: '2023-04-20T10:24:36.162Z'
          description: Time of last update to category
        createdAt:
          type: string
          example: '2021-04-20T10:24:36.162Z'
          description: Time of category creation
    genericError:
      type: object
      description: Error details
      properties:
        message:
          type: string
          description: Error message
          example: Request was invalid
        type:
          type: string
          description: Error type
          example: Bad request
        errors:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                description: Error type
                example: CLIENT_ERROR
              message:
                type: string
                description: Brief error message
                example: Invalid request
    simpleMultiStringSearchOperation:
      type: object
      description: Multi-string search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a `string` type
          example: IN
          enum:
            - IN
        value:
          type: array
          items:
            $ref: '#/components/schemas/stringSchema'
    simpleSingleStringSearchOperation:
      type: object
      description: Simple single-string search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a `string` type
          example: EQUALS
          enum:
            - EQUALS
        value:
          $ref: '#/components/schemas/stringSchema'
    singleStringSearchOperation:
      type: object
      description: Single string search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a `string` type
          example: EQUALS
          enum:
            - EQUALS
            - CONTAINS
        value:
          $ref: '#/components/schemas/stringSchema'
    booleanSchema:
      type: boolean
      nullable: true
      description: Sample boolean schema
      example: true
    attributeValueInfo:
      anyOf:
        - $ref: '#/components/schemas/localizedStringSearchOperation'
        - $ref: '#/components/schemas/booleanSearchOperation'
        - $ref: '#/components/schemas/numberSearchOperation'
    datetimeRangeOperation:
      type: object
      description: Date range search
      required:
        - op
        - fromValue
        - toValue
      properties:
        op:
          type: string
          description: Search operation performed on a date range
          example: RANGE
          enum:
            - RANGE
        fromValue:
          type: string
          description: Starting range (UTC)
          example: '2022-04-20T10:24:36.162Z'
        toValue:
          type: string
          description: Ending range (UTC)
          example: '2023-04-20T10:24:36.162Z'
    datetimeInOperation:
      type: object
      description: Date-time search based on IN condition
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: >-
            Operations that can be performed on a date type. That is, equals to,
            less than, greater than, less than or equal to, and greater than or
            equal to
          example: IN
          enum:
            - IN
        value:
          type: array
          items:
            type: string
            description: Time to be searched (UTC)
            example: '2021-04-20T10:24:36.162Z'
    datetimeOperation:
      type: object
      description: Date-time search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: >-
            Operations that can be performed on a `number` type such as equals
            to, less than (LT), Greater than (GT), Less than or equal to (LTE),
            Greater than or equal to (GTE), etc.
          example: GTE
          enum:
            - EQUALS
            - LTE
            - GTE
            - LT
            - GT
        value:
          type: string
          description: Time to be searched (UTC)
          example: '2022-04-20T10:24:36.162Z'
    localizedProperties:
      type: object
      description: Localized details
      additionalProperties:
        type: object
        properties:
          name:
            description: Localized name
            type: string
            example: Color
      example:
        en-US:
          name: Color
        en-IN:
          name: Colour
    attribute:
      type: object
      description: Attribute details
      properties:
        id:
          type: string
          example: 64184766610c0e32a86d8758
          description: 24-character system-generated attribute ID
        name:
          type: string
          example: color
          description: Non-localized attribute name
        localizedProperties:
          $ref: '#/components/schemas/localizedProperties'
        isLocalizable:
          type: boolean
          example: true
          description: >-
            true: Attribute name can be translated into different languages or
            localized for different regions. <br /> false: Attribute name can't
            be localized. **Note**: Refer to `localizedProperties` to get
            relevant attributes based on locale.
        isInherited:
          type: boolean
          example: true
          description: >-
            true: Attribute is inherited from its parent. <br /> false:
            Attribute isn't inherited from parent
        type:
          type: string
          example: TEXT
          description: Attribute type
        validation:
          $ref: '#/components/schemas/dateTypeAttributeValidation'
        value:
          description: Attribute value
          anyOf:
            - $ref: '#/components/schemas/booleanSchema'
            - $ref: '#/components/schemas/stringSchema'
            - $ref: '#/components/schemas/doubleSchema'
            - $ref: '#/components/schemas/integerSchema'
            - $ref: '#/components/schemas/dateSchema'
          example: blue
    stringSchema:
      type: string
      nullable: true
      description: Sample string schema
      example: blue
    localizedStringSearchOperation:
      allOf:
        - $ref: '#/components/schemas/advancedStringSearchOperation'
      type: object
      description: Search criteria based on localized data
      properties:
        locale:
          type: string
          description: >-
            If `isLocalizable` is true, searches for the requested name in the
            list of locales provided here. If `isLocalizable` is false, searches
            for the non-localized names.
          example: en_US
    numberSearchOperation:
      type: object
      description: Number search
      anyOf:
        - $ref: '#/components/schemas/singleNumberSearchOperation'
        - $ref: '#/components/schemas/multiNumberSearchOperation'
    dateTypeAttributeValidation:
      type: object
      description: Attribute validation - date
      properties:
        dateFormat:
          type: string
          example: MM-DD-YYYY
          description: Date format. <br /> Applicable when attributeType is `DATETIME`.
    doubleSchema:
      type: number
      nullable: true
      format: double
      description: Sample double schema
      example: 1
    integerSchema:
      type: integer
      nullable: true
      format: int32
      description: Sample integer schema
      example: 1
    dateSchema:
      type: string
      format: date
      nullable: true
      description: Sample date schema
      example: '2022-12-31T00:00:00.000Z'
    advancedStringSearchOperation:
      type: object
      description: Advanced string search
      anyOf:
        - $ref: '#/components/schemas/advancedMultiStringSearchOperation'
        - $ref: '#/components/schemas/advancedSingleStringSearchOperation'
    singleNumberSearchOperation:
      type: object
      description: Single number search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: >-
            Operations that can be performed on a `number` type such as equals
            to, less than (LT), Greater than (GT), Less than or equal to (LTE),
            Greater than or equal to (GTE), etc.
          example: GTE
          enum:
            - EQUALS
            - LTE
            - GTE
            - LT
            - GT
        value:
          $ref: '#/components/schemas/doubleSchema'
    multiNumberSearchOperation:
      type: object
      description: Multiple numbers search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: In operation on a `number` type
          example: IN
          enum:
            - IN
        value:
          type: array
          items:
            $ref: '#/components/schemas/doubleSchema'
    advancedMultiStringSearchOperation:
      type: object
      description: Advanced multi-string search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a `string` type
          example: IN
          enum:
            - IN
            - NOT_IN
        value:
          type: array
          items:
            $ref: '#/components/schemas/stringSchema'
    advancedSingleStringSearchOperation:
      type: object
      description: Advanced single-string search
      required:
        - op
        - value
      properties:
        op:
          type: string
          description: Operations that can be performed on a string type
          example: EQUALS
          enum:
            - EQUALS
            - CONTAINS
            - NOT_EQUALS
        value:
          $ref: '#/components/schemas/stringSchema'
  headers:
    x-fabric-request-id-header:
      description: Unique request ID
      schema:
        type: string
        example: 263e731c-45c8-11ed-b878-0242ac120002
  responses:
    badRequest:
      description: Request is invalid or malformed
      headers:
        x-fabric-request-id:
          $ref: '#/components/headers/x-fabric-request-id-header'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
    notAuthorized:
      description: Unauthorized requester
      headers:
        x-fabric-request-id:
          $ref: '#/components/headers/x-fabric-request-id-header'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          example:
            message: The requester is unauthorized
            type: UNAUTHORIZED_ERROR
    forbidden:
      description: User isn't allowed to perform the action
      headers:
        x-fabric-request-id:
          $ref: '#/components/headers/x-fabric-request-id-header'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          example:
            type: REQUEST_DENIED
            message: User doesn't have the required permission
    payloadLimitExceededError:
      description: Payload limit exceeded (> 10MB)
      headers:
        x-fabric-request-id:
          $ref: '#/components/headers/x-fabric-request-id-header'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          example:
            type: PAYLOAD_LIMIT_EXCEEDED_ERROR
            message: The payload exceeds maximum configured size
    internalServerError:
      description: Internal server error
      headers:
        x-fabric-request-id:
          $ref: '#/components/headers/x-fabric-request-id-header'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/genericError'
          example:
            type: SERVER_ERROR
            message: Internal Server Error
  securitySchemes:
    authorization:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: S2S access token (JWT) from fabric Identity service (during Login)

````