openapi: 3.0.0
x-stoplight:
  id: 6qd4aml6o2zo2
info:
  description: |-
    The Platform API is used to upload, update, and retrieve product data, implement product search, and display related products on product detail pages.

    ### Authentication

    Some endpoints are public and do not require authentication. Endpoints that require authentication are marked with the lock icon.

    Authentication uses an API key passed in the `Authorization` header with the `Bearer` scheme:

    ```
    Authorization: Bearer YOUR_KEY
    ```

    [Generate API keys in Data Platform](https://docs.zoovu.com/data-platform/integrations/api-keys).

    Example request:

    ```
    GET https://api.data.zoovu.com/projects?projectId=12345
    Authorization: Bearer YOUR_KEY
    ```

    ### Projects

    All endpoints require a `projectId`. The project identifies the data source for your request — for example, using a German project returns German results. Find your project IDs in the [Data Platform](https://data.zoovu.com/projects) or via the [List projects](https://docs.zoovu.com/api/platform-api/list-projects) endpoint.

    ### Getting Started

    To push products into your Data Platform project:

    1. [Initiate a full update](https://docs.zoovu.com/api/platform-api/initiate-full-update)
    2. [Upload batches of products](https://docs.zoovu.com/api/platform-api/upload-batch-of-products)
    3. [Commit the full update](https://docs.zoovu.com/api/platform-api/commit-full-update)

    After committing, your products appear in the Data Platform and, if applicable, in Search Studio.

    ### Support

    If you need assistance, contact [Zoovu Support](https://help.desk.zoovu.io/servicedesk/customer/portals).
  title: Platform API
  version: '1.0'
  license:
    name: Zoovu
    url: 'https://zoovu.com'
servers:
  - url: 'https://api.data.zoovu.com'
tags:
  - name: Product Data
    description: Data management related endpoints
  - name: Product Search
    description: Search related endpoints
  - name: Ontology Management
    description: Ontology management related endpoints
  - name: Tasks
    description: Task monitoring endpoints
  - name: Filters
    description: Filter configuration endpoints
  - name: Content
    description: Content results management endpoints
  - name: Accounting
    description: Account and credential management endpoints
paths:
  '/products/batch/initiate':
    parameters:
      - schema:
          type: integer
        name: projectId
        in: query
        required: true
        description: your Data Platform project ID
    post:
      summary: Full update step 1 - Initiate
      tags:
        - Product Data
      operationId: initiate-full-update
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"message\": \"You can now send batches of the full update\",\r\n    \"status\": \"success\"\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  task:
                    type: object
                    properties:
                      projectId:
                        type: integer
                      taskStatus:
                        type: string
                      failure:
                        type: boolean
                      requestTime:
                        type: string
                      startTime:
                        type: string
                      finishTime:
                        type: string
                        nullable: true
                      nrOfItems:
                        type: integer
                      nrOfProcessedItems:
                        type: integer
                      progress:
                        type: number
                      id:
                        type: string
              example:
                message: You can now send batches
                status: success
                task:
                  projectId: 5
                  taskStatus: FINISHED
                  failure: false
                  requestTime: '1580461429402'
                  startTime: '1580461429405'
                  finishTime: '1580461429945'
                  nrOfItems: 1
                  nrOfProcessedItems: 1
                  progress: 1
                  id: 5e33ed753484b21cb8f42cf9
        '404':
          description: "Not found\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      x-stoplight:
        id: e6asjrrf74uwx
      description: "Use this endpoint to initiate a full update (step 1). \r\n\r\nAfter calling this endpoint, you can send batches of products in separate requests using the [\"Full update step 2 - Upload batches\"](https://docs.zoovu.com/api/platform-api/upload-batch-of-products) endpoint (step 2). \r\n\r\nFinally, trigger the update with the [\"Full update step 3 - Commit\"](https://docs.zoovu.com/api/platform-api/commit-full-update) endpoint (step 3). Please note - **any products that were previously uploaded but were not included in the latest batches will be deleted in step 3**!\r\n"
      security:
        - apiKeyHeader: []
  '/products/batch/upload':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    post:
      summary: Full update step 2 - Upload batches
      tags:
        - Product Data
      operationId: upload-batch-of-products
      parameters:
        - schema:
            type: boolean
          name: partial
          in: query
          description: 'When set to true, only the attributes included in the request are updated while existing attributes are preserved. If the product does not exist yet, a new product is created. When omitted or false, all product information per SKU in the request is replaced — attributes not included are removed.'
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"message\": \"Upload initiated\",\r\n    \"status\": \"success\",\r\n    \"task\": {\r\n        \"projectId\": 39074,\r\n        \"projectName\": null,\r\n        \"origin\": \"LIVE-API\",\r\n        \"taskStatus\": \"PENDING\",\r\n        \"name\": \"\",\r\n        \"taskIncrementType\": \"ITEM_BASED\",\r\n        \"failure\": false,\r\n        \"requestTime\": 1744211013700,\r\n        \"startTime\": 1744211013728,\r\n        \"finishTime\": null,\r\n        \"progress\": 0,\r\n        \"logCounter\": 1,\r\n        \"id\": \"67f68c453254c723d5ff0aee\"\r\n    },\r\n    \"nrOfSent\": 500,\r\n    \"nrOfParsed\": 500\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    message: Upload initiated
                    status: success
                    task:
                      projectId: 39074
                      projectName: null
                      origin: LIVE-API
                      taskStatus: PENDING
                      name: ''
                      taskIncrementType: ITEM_BASED
                      failure: false
                      requestTime: 1744119045828
                      startTime: null
                      finishTime: null
                      progress: 0
                      logCounter: 0
                      id: 67f525053254c723d5fedb26
                    nrOfSent: 5
                    nrOfParsed: 5
                properties:
                  message:
                    type: string
                    example: Upload initiated
                  status:
                    type: string
                    example: success
                  task:
                    type: object
                    properties:
                      projectId:
                        type: integer
                      projectName:
                        nullable: true
                      origin:
                        type: string
                        example: LIVE-API
                      taskStatus:
                        type: string
                        example: PENDING
                      name:
                        type: string
                      taskIncrementType:
                        type: string
                        example: ITEM_BASED
                      failure:
                        type: boolean
                      requestTime:
                        type: integer
                      startTime:
                        nullable: true
                      finishTime:
                        nullable: true
                      progress:
                        type: integer
                      logCounter:
                        type: integer
                      id:
                        type: string
                  nrOfSent:
                    type: integer
                  nrOfParsed:
                    type: integer
        '400':
          description: "Bad Request\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 400,\r\n    \"message\": \"Your body params are not valid\"\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    status: failure
                    code: 400
                    message: Your body params are not valid
                properties:
                  status:
                    type: string
                    example: failure
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: Your body params are not valid
        '404':
          description: "Not found\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      x-stoplight:
        id: 0p8ecmalgdxz8
      requestBody:
        content:
          application/json:
            schema:
              example:
                products:
                  - identifier: PRD-9876-BLK42
                    groupIdentifier: '9876'
                    name: Laptop 9876 Black
                    productUrl: www.myshop.com/product/9876-blk42
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    settings:
                      includeUserGroups:
                        - '23'
                        - '42'
                      excludeUserGroups:
                        - '64'
                    image: www.myshop.com/product/9876-blk42/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Black
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '5.0'
                  - identifier: PRD-9876-WHT38
                    groupIdentifier: '9876'
                    name: Laptop 9876 White
                    productUrl: www.myshop.com/product/9876-wht38
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    images:
                      - url: www.myshop.com/product/9876-wht38/img1.jpg
                        type: ALTERNATIVE
                      - url: www.myshop.com/product/9876-wht38/img2.jpg
                        type: ALTERNATIVE
                      - url: www.myshop.com/product/9876-wht38/img3.jpg
                        type: ALTERNATIVE
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: White
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '4.7'
                  - identifier: PRD-9876-RED44
                    groupIdentifier: '9876'
                    name: Laptop 9876 Red
                    productUrl: www.myshop.com/product/9876-red44
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    image: www.myshop.com/product/9876-red44/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Red
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '4.8'
                  - identifier: PRD-9876-BLU40
                    groupIdentifier: '9876'
                    name: Laptop 9876 Blue
                    productUrl: www.myshop.com/product/9876-blu40
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    image: www.myshop.com/product/9876-blu40/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Blue
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '4.6'
                  - identifier: PRD-9876-GRN36
                    groupIdentifier: '9876'
                    name: Laptop 9876 Green
                    productUrl: www.myshop.com/product/9876-grn36
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    image: www.myshop.com/product/9876-grn36/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Green
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '4.9'
              type: object
              x-examples:
                Example 1:
                  products:
                    - identifier: PRD-9876-BLK42
                      groupIdentifier: '9876'
                      name: Laptop 9876 Black
                      productUrl: www.myshop.com/product/9876-blk42
                      categories:
                        - path:
                            - Electronics
                            - Laptops
                      settings:
                        includeUserGroups:
                          - '23'
                          - '42'
                        excludeUserGroups:
                          - '64'
                      image: www.myshop.com/product/9876-blk42/img.jpg
                      attributes:
                        - key: brand
                          value: BrandX
                        - key: color
                          value: Black
                        - key: price
                          value: $899.99
                        - key: rating
                          value: '5.0'
                    - identifier: PRD-9876-WHT38
                      groupIdentifier: '9876'
                      name: Laptop 9876 White
                      productUrl: www.myshop.com/product/9876-wht38
                      categories:
                        - path:
                            - Electronics
                            - Laptops
                      images:
                        - url: www.myshop.com/product/9876-wht38/img1.jpg
                          type: ALTERNATIVE
                        - url: www.myshop.com/product/9876-wht38/img2.jpg
                          type: ALTERNATIVE
                        - url: www.myshop.com/product/9876-wht38/img3.jpg
                          type: ALTERNATIVE
                      attributes:
                        - key: brand
                          value: BrandX
                        - key: color
                          value: White
                        - key: price
                          value: $899.99
                        - key: rating
                          value: '4.7'
                    - identifier: PRD-9876-RED44
                      groupIdentifier: '9876'
                      name: Laptop 9876 Red
                      productUrl: www.myshop.com/product/9876-red44
                      categories:
                        - path:
                            - Electronics
                            - Laptops
                      image: www.myshop.com/product/9876-red44/img.jpg
                      attributes:
                        - key: brand
                          value: BrandX
                        - key: color
                          value: Red
                        - key: price
                          value: $899.99
                        - key: rating
                          value: '4.8'
                    - identifier: PRD-9876-BLU40
                      groupIdentifier: '9876'
                      name: Laptop 9876 Blue
                      productUrl: www.myshop.com/product/9876-blu40
                      categories:
                        - path:
                            - Electronics
                            - Laptops
                      image: www.myshop.com/product/9876-blu40/img.jpg
                      attributes:
                        - key: brand
                          value: BrandX
                        - key: color
                          value: Blue
                        - key: price
                          value: $899.99
                        - key: rating
                          value: '4.6'
                    - identifier: PRD-9876-GRN36
                      groupIdentifier: '9876'
                      name: Laptop 9876 Green
                      productUrl: www.myshop.com/product/9876-grn36
                      categories:
                        - path:
                            - Electronics
                            - Laptops
                      image: www.myshop.com/product/9876-grn36/img.jpg
                      attributes:
                        - key: brand
                          value: BrandX
                        - key: color
                          value: Green
                        - key: price
                          value: $899.99
                        - key: rating
                          value: '4.9'
              properties:
                products:
                  type: array
                  items:
                    type: object
                    properties:
                      identifier:
                        type: string
                        description: your internally used product ID
                      groupIdentifier:
                        type: string
                        description: an identifier used to group variants of the same product
                      name:
                        type: string
                        description: the product name
                      productUrl:
                        type: string
                        description: URL to the product detail page
                      categories:
                        type: array
                        items:
                          type: object
                          properties:
                            path:
                              type: array
                              description: the category path of the product
                              items:
                                type: string
                      settings:
                        type: object
                        properties:
                          includeUserGroups:
                            type: array
                            description: 'which user groups should see the product. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
                            items:
                              type: string
                          excludeUserGroups:
                            type: array
                            description: 'which user groups should not see the product. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
                            items:
                              type: string
                      image:
                        type: string
                        description: URL to the product image
                      images:
                        type: array
                        x-stoplight:
                          id: 3o9vhgzqv7teq
                        items:
                          x-stoplight:
                            id: ua7vwk9iyd9u7
                          type: object
                          properties:
                            url:
                              type: string
                              x-stoplight:
                                id: y24isgcz6iles
                              description: URL(s) to additional images
                            type:
                              type: string
                              x-stoplight:
                                id: ra0ekkgt9fqlk
                              description: type should be ALTERNATIVE
                      attributes:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              description: attribute names like "Color" and "Price"
                            value:
                              type: string
                              description: 'the corresponding value for the attributes (e.g., "Red" and "29.99")'
                            settings:
                              type: array
                              x-stoplight:
                                id: ttly2s5qw4rfb
                              description: 'There are two special flags for price attributes: "oldPrice" and "newPrice". These can be included within a "settings" property on the corresponding price attributes, allowing strike prices and current prices to be programmatically defined.'
                              items:
                                x-stoplight:
                                  id: akiw50r85bra0
                                type: object
                                properties:
                                  oldPrice:
                                    type: boolean
                                    x-stoplight:
                                      id: fhxepfdd1flat
                                    description: "```json\r\n{ \r\n  \"key\": \"strike price\", \r\n  \"value\":\"9,99 EUR\", \r\n  \"settings\": {\r\n    \"oldPrice\": true\r\n  }\r\n}\r\n```"
                                  newPrice:
                                    type: boolean
                                    x-stoplight:
                                      id: 7bhsbfekp6jny
                                    description: "```json\r\n{ \r\n  \"key\": \"price\", \r\n  \"value\":\"19,99 EUR\", \r\n  \"settings\": {\r\n    \"newPrice\": true\r\n  }\r\n}\r\n```"
                            userGroups:
                              type: string
                              x-stoplight:
                                id: mnawsss3qkdst
                              description: 'which user group(s) this key-value pair applies to. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
        description: ''
      description: |-
        Use this endpoint to upload a batch of products following the example JSON schema. Each batch can contain **up to 10,000 products**. Repeat this step until all products have been uploaded.

        If the uploaded JSON breaks the JSON schema, you will get detailed information about the error in the API response. 

        Please check the `status` attribute in the JSON response after each batch.
        The response should contain `status: success`. Only proceed with the next batch if the request was successful.

        *Important*: all attribute objects in the `attributes` array need to have the **value given as a string**. Even numeric values need to be converted to strings. Additonally, numeric values must have a unit, such as "EUR" for the "Price" attribute or "in" for "Length".
      security:
        - apiKeyHeader: []
  '/products/batch/start':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    post:
      summary: Full update step 3 - Commit
      tags:
        - Product Data
      operationId: commit-full-update
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"status\": \"success\",\r\n    \"data\": {\r\n        \"message\": \"Batch update started\",\r\n        \"status\": \"success\",\r\n        \"task\": {\r\n            \"projectId\": 39074,\r\n            \"projectName\": null,\r\n            \"origin\": \"LIVE-API\",\r\n            \"taskStatus\": \"RUNNING\",\r\n            \"name\": \"Api triggered full update\",\r\n            \"taskIncrementType\": \"STEP_BASED\",\r\n            \"failure\": false,\r\n            \"requestTime\": 1744638748765,\r\n            \"startTime\": 1744638748766,\r\n            \"finishTime\": null,\r\n            \"progress\": 0,\r\n            \"logCounter\": 3,\r\n            \"id\": \"67fd131c34ff64223a195b14\"\r\n        }\r\n    }\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    status: success
                    data:
                      message: Batch update started
                      status: success
                      task:
                        projectId: 39074
                        projectName: null
                        origin: LIVE-API
                        taskStatus: RUNNING
                        name: Api triggered full update
                        taskIncrementType: STEP_BASED
                        failure: false
                        requestTime: 1744119368407
                        startTime: 1744119368408
                        finishTime: null
                        progress: 0
                        logCounter: 3
                        id: 67f526483254c723d5fedb35
                properties:
                  status:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: Batch update started
                      status:
                        type: string
                        example: success
                      task:
                        type: object
                        properties:
                          projectId:
                            type: integer
                          projectName:
                            nullable: true
                          origin:
                            type: string
                            example: LIVE-API
                          taskStatus:
                            type: string
                            example: RUNNING
                          name:
                            type: string
                            example: Api triggered full update
                          taskIncrementType:
                            type: string
                            example: STEP_BASED
                          failure:
                            type: boolean
                          requestTime:
                            type: integer
                          startTime:
                            type: integer
                          finishTime:
                            nullable: true
                          progress:
                            type: integer
                          logCounter:
                            type: integer
                          id:
                            type: string
        '400':
          description: "Bad Request\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"message\": \"The last full update has been rejected because the number of products was significantly lower than before.\",\r\n    \"code\": 400\r\n}\r\n```"
        '404':
          description: "```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      x-stoplight:
        id: f36rs4kamcsin
      description: This endpoint starts an update to process the batches of products uploaded using the "Full update step 2 - Upload batches" endpoint. Remember - any products that were previously uploaded but were not included in the most recent batches **will be deleted** after calling this endpoint.
      security:
        - apiKeyHeader: []
  '/products':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    post:
      summary: Update products incrementally
      operationId: update-products-incrementally
      tags:
        - Product Data
      parameters:
        - schema:
            type: boolean
          name: partial
          in: query
          description: When partial is set to true only the attributes that are part of the product input are updated while other attributes are untouched
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"message\": \"Your update will now be started\",\r\n    \"status\": \"success\",\r\n    \"task\": {\r\n        \"projectId\": 39074,\r\n        \"projectName\": null,\r\n        \"origin\": \"LIVE-API\",\r\n        \"taskStatus\": \"RUNNING\",\r\n        \"name\": \"incremental partial update\",\r\n        \"taskIncrementType\": \"STEP_BASED\",\r\n        \"failure\": false,\r\n        \"requestTime\": 1744640901632,\r\n        \"startTime\": 1744640901634,\r\n        \"finishTime\": null,\r\n        \"progress\": 0,\r\n        \"logCounter\": 3,\r\n        \"id\": \"67fd1b8534ff64223a195b9f\"\r\n    },\r\n    \"nrOfSent\": 3000,\r\n    \"nrOfParsed\": 3000\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  task:
                    type: object
                    properties:
                      projectId:
                        type: integer
                      taskStatus:
                        type: string
                      failure:
                        type: boolean
                      requestTime:
                        type: string
                      startTime:
                        type: string
                      finishTime:
                        type: string
                        nullable: true
                      nrOfItems:
                        type: integer
                      progress:
                        type: number
                      id:
                        type: string
                  nrOfSent:
                    type: integer
                  nrOfParsed:
                    type: integer
                  validation:
                    type: array
                    items:
                      type: object
              example:
                message: Update will now be started
                status: success
                task:
                  projectId: 24
                  taskStatus: RUNNING
                  failure: false
                  requestTime: '1590586874330'
                  startTime: '1590586874331'
                  finishTime: null
                  nrOfItems: 3
                  progress: 0
                  id: 5ece6dfa1072dd052fbc210b
                validation:
                  - {}
                  - {}
                  - {}
        '404':
          description: "Not found\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      x-stoplight:
        id: ooynhi8m5h100
      description: |-
        This endpoint supports two update modes: **incremental** and **partial**. Understanding the difference is important for choosing the right approach.

        | | Incremental update (`partial` omitted or `false`) | Partial update (`partial=true`) |
        |---|---|---|
        | **What it does** | Replaces all product information per SKU in the request. Attributes not included in the request are removed. | Updates only the attributes included in the request. Existing attributes not in the request are preserved. |
        | **Use case** | Batch updates throughout the day — e.g., syncing product data periodically. | High-frequency price and stock updates — e.g., keeping availability current. |
        | **Max products per request** | 10,000 | 10,000 |
        | **Recommended frequency** | Not designed to run every minute with 10,000 products. | Safe to run every minute with 10,000 products. |

        ---

        This endpoint can be used to **update a single product or a subset of products** (up to 10,000 products).

        To update a larger number of products, first use the ["Full update step 2 - Upload batches" endpoint](https://docs.zoovu.com/api/platform-api/upload-batch-of-products) to send multiple batches of products in separate requests, and then start the update process using the ["Full update step 3 - Commit" endpoint](https://docs.zoovu.com/api/platform-api/commit-full-update).

        You can also use this endpoint to **update a single attribute** (e.g., price) or a few attributes (e.g., price, availability, and sales count) by **setting the parameter `partial` to true** and only sending attributes that need to be updated in the attributes object. This kind of update is also suitable for a maximum of 10,000 products per request.

        Please note: **only full updates create new attributes** in your ontology (if you do not [provide your own ontology](https://docs.zoovu.com/api/platform-api/create-or-update-concepts)). Incremental or partial updates affect your product data, *not* your ontology.

        If the uploaded JSON breaks the JSON schema, you will get detailed information about the error in the API response.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                products:
                  - identifier: PRD-9876-BLK42
                    groupIdentifier: '9876'
                    name: Laptop 9876 Black
                    productUrl: www.myshop.com/product/9876-blk42
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    settings:
                      includeUserGroups:
                        - '23'
                        - '42'
                      excludeUserGroups:
                        - '64'
                    image: www.myshop.com/product/9876-blk42/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Black
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '5.0'
                  - identifier: PRD-9876-GRN36
                    groupIdentifier: '9876'
                    name: Laptop 9876 Green
                    productUrl: www.myshop.com/product/9876-grn36
                    categories:
                      - path:
                          - Electronics
                          - Laptops
                    image: www.myshop.com/product/9876-grn36/img.jpg
                    attributes:
                      - key: brand
                        value: BrandX
                      - key: color
                        value: Green
                      - key: price
                        value: $899.99
                      - key: rating
                        value: '4.9'
              properties:
                products:
                  type: array
                  items:
                    type: object
                    properties:
                      identifier:
                        type: string
                        description: your internally used product ID
                      groupIdentifier:
                        type: string
                        description: an identifier used to group variants of the same product
                      name:
                        type: string
                        description: the product name
                      productUrl:
                        type: string
                        description: URL to the product detail page
                      categories:
                        type: array
                        items:
                          type: object
                          properties:
                            path:
                              type: array
                              description: the category path of the product
                              items:
                                type: string
                      settings:
                        type: object
                        properties:
                          includeUserGroups:
                            type: array
                            description: 'which user groups should see the product. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
                            items:
                              type: string
                          excludeUserGroups:
                            type: array
                            description: 'which user groups should not see the product. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
                            items:
                              type: string
                      image:
                        type: string
                        description: URL to the product image
                      images:
                        type: array
                        x-stoplight:
                          id: aqibrxi1191ey
                        items:
                          x-stoplight:
                            id: b6am9ca1zd0bh
                          type: object
                          properties:
                            url:
                              type: string
                              x-stoplight:
                                id: d4hc1it67ayvj
                              description: URL(s) to additional images
                            type:
                              type: string
                              x-stoplight:
                                id: d5hd2lo1i5wyl
                      attributes:
                        type: array
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              description: attribute names like "Color" and "Price"
                            value:
                              type: string
                              description: 'the corresponding value for the attributes (e.g., "Red" and "29.99")'
                            userGroups:
                              type: string
                              x-stoplight:
                                id: xfnlgz31c95ii
                              description: 'which user group(s) this key-value pair applies to. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
        description: ''
      security:
        - apiKeyHeader: []
    delete:
      summary: Delete products
      tags:
        - Product Data
      security:
        - apiKeyHeader: []
      operationId: delete-products
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"message\": \"Delete will now be started\",\r\n    \"status\": \"success\",\r\n    \"task\": {\r\n        \"projectId\": 39074,\r\n        \"projectName\": null,\r\n        \"origin\": \"LIVE-API\",\r\n        \"taskStatus\": \"RUNNING\",\r\n        \"name\": \"delete products\",\r\n        \"taskIncrementType\": \"STEP_BASED\",\r\n        \"failure\": false,\r\n        \"requestTime\": 1745927790509,\r\n        \"startTime\": 1745927790510,\r\n        \"finishTime\": null,\r\n        \"progress\": 0,\r\n        \"logCounter\": 3,\r\n        \"id\": \"6810be6e3fd591567b20c499\"\r\n    }\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  status:
                    type: string
                  task:
                    type: object
                    properties:
                      projectId:
                        type: integer
                      taskStatus:
                        type: string
                      failure:
                        type: boolean
                      requestTime:
                        type: string
                      startTime:
                        type: string
                      finishTime:
                        type: string
                        nullable: true
                      nrOfItems:
                        type: integer
                      nrOfProcessedItems:
                        type: integer
                      progress:
                        type: number
                      id:
                        type: string
              example:
                message: Delete will now be started
                status: success
                task:
                  projectId: 5
                  taskStatus: RUNNING
                  failure: false
                  requestTime: '1580461419542'
                  startTime: '1580461419547'
                  finishTime: null
                  nrOfItems: 1
                  nrOfProcessedItems: 0
                  progress: 0
                  id: 5e33ed6b3484b21cb8f42cf7
        '400':
          description: "Bad Request\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 400,\r\n    \"message\": \"You have to send at least one known product identifier. Requested identifier to delete were: {\\n  \\\"identifiers\\\": [\\n    \\\"PRD-9876-RED443\\\"\\n  ]\\n}\"\r\n}\r\n```"
        '404':
          description: "Not found\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      x-stoplight:
        id: g4nzefpc9pd24
      description: |-
        This endpoint deletes all products whose identifiers are provided in the request body.

        If you need to delete a large number of products, or remove products without specifying a list of identifiers, consider using the full update process instead (i.e., initiate full update, upload batches of products, commit full update). Any products not included in this new data load will be automatically deleted.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                identifiers:
                  - 6379b9_E
                  - 6379b9_F
              required:
                - identifiers
              properties:
                identifiers:
                  type: array
                  description: the identifiers of the products to delete
                  items:
                    type: string
        description: ''
  '/product-service':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
        example: 123456
      - schema:
          type: string
        name: identifier
        description: your internally used product ID
        example: IRB-50920
        in: query
        required: true
      - schema:
          type: string
        name: maskTag
        in: query
        required: false
        description: 'Filters resolved masks by tag. Matching masks are attached as a `masks` array on each fact whose attribute is included in the mask. Can be used together with `maskType` — type filtering is applied first, then tag filtering.'
        example: zoe
      - schema:
          type: string
          enum:
            - PIM
            - MINI_PDP
            - REFINEMENT
            - ZOE
            - PASS_ON
            - PASS_ON_SUGGESTION
            - ASSISTANT
            - MCP
            - RELATIONS
        name: maskType
        in: query
        required: false
        description: 'Filters resolved masks by type. Matching masks are attached as a `masks` array on each fact whose attribute is included in the mask. Can be used together with `maskTag` — type filtering is applied first, then tag filtering. Case-insensitive.'
        example: MINI_PDP
      - schema:
          type: boolean
        name: siblings
        in: query
        required: false
        description: 'If true, includes sibling variants (products with the same groupIdentifier) in the response.'
      - schema:
          type: boolean
        name: attributeDescription
        in: query
        required: false
        description: 'If true, includes attribute descriptions in the response facts.'
      - schema:
          type: boolean
        name: filterFacts
        in: query
        required: false
        description: 'If true and masks are being resolved (via `maskType` or `maskTag`), only facts that have at least one matching mask are kept in the response. Facts without matching masks are removed. Has no effect when neither `maskType` nor `maskTag` is provided.'
    get:
      summary: Get product details
      x-slug: /api/platform-api/products/get-detail
      tags:
        - Product Data
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"id\": 241659429,\r\n    \"identifier\": \"3344561\",\r\n    \"groupId\": \"3344561\",\r\n    \"name\": \"Laptop AH\",\r\n    \"link\": \"www.myshop.com/product/3344561\",\r\n    \"images\": [\r\n        {\r\n            \"url\": \"www.myshop.com/product/3344561/img.jpg\",\r\n            \"type\": \"SMALL\"\r\n        }\r\n    ],\r\n    \"categories\": [\r\n        {\r\n            \"path\": [\r\n                \"Laptops\"\r\n            ],\r\n            \"categoryId\": 291156242\r\n        }\r\n    ],\r\n    \"facts\": [\r\n        {\r\n            \"attributeId\": 288188589,\r\n            \"attribute\": \"Brand\",\r\n            \"valueId\": 292189243,\r\n            \"value\": \"BrandW\",\r\n            \"type\": \"TEXT_ATTRIBUTE\"\r\n        },\r\n        {\r\n            \"attributeId\": 281560514,\r\n            \"attribute\": \"Color\",\r\n            \"valueId\": 281663979,\r\n            \"value\": \"BLUE\",\r\n            \"type\": \"TEXT_ATTRIBUTE\"\r\n        },\r\n        {\r\n            \"attributeId\": 288188381,\r\n            \"attribute\": \"Price\",\r\n            \"value\": \"1299.99\",\r\n            \"type\": \"NUMERIC_ATTRIBUTE\",\r\n            \"unit\": \"\"\r\n        },\r\n        {\r\n            \"attributeId\": 288188390,\r\n            \"attribute\": \"Color\",\r\n            \"valueId\": 288188596,\r\n            \"value\": \"Blue\",\r\n            \"type\": \"TEXT_ATTRIBUTE\"\r\n        },\r\n        {\r\n            \"attributeId\": 288188587,\r\n            \"attribute\": \"Rating\",\r\n            \"value\": \"4.20\",\r\n            \"type\": \"NUMERIC_ATTRIBUTE\",\r\n            \"unit\": \"\"\r\n        },\r\n        {\r\n            \"attributeId\": 281559599,\r\n            \"attribute\": \"All Products\",\r\n            \"value\": \"TRUE\",\r\n            \"type\": \"BOOLEAN_ATTRIBUTE\"\r\n        }\r\n    ],\r\n    \"lastUpdateTs\": 1745928435738\r\n}\r\n```"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
              examples:
                Example 1:
                  value:
                    status: failure
                    code: 401
                    message: You are not allowed to access the requested resource
        '404':
          description: Not Found
      operationId: get-product-detail-information
      x-stoplight:
        id: 6r03e16dv1hyy
      description: |-
        Returns detailed product information for a single product. The *identifier* is your internally used product ID.
        This corresponds with the *identifier* field in the product search response.
      security:
        - apiKeyHeader: []
  '/product-service/products-by-sku':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
        example: '123456'
      - schema:
          type: string
        name: identifiers
        description: 'a JSON array of product identifiers (your internally used product IDs), e.g. `["PRD-001","PRD-002","PRD-003"]`'
        in: query
        required: true
        example: '["IRB-50920","IRB-50921"]'
      - schema:
          type: string
        name: maskTag
        in: query
        required: false
        description: 'Filters resolved masks by tag. Matching masks are attached as a `masks` array on each fact whose attribute is included in the mask. Can be used together with `maskType` — type filtering is applied first, then tag filtering.'
        example: zoe
      - schema:
          type: string
          enum:
            - PIM
            - MINI_PDP
            - REFINEMENT
            - ZOE
            - PASS_ON
            - PASS_ON_SUGGESTION
            - ASSISTANT
            - MCP
            - RELATIONS
        name: maskType
        in: query
        required: false
        description: 'Filters resolved masks by type. Matching masks are attached as a `masks` array on each fact whose attribute is included in the mask. Can be used together with `maskTag` — type filtering is applied first, then tag filtering. Case-insensitive.'
        example: MINI_PDP
      - schema:
          type: boolean
        name: siblings
        in: query
        required: false
        description: 'If true, includes sibling variants (products with the same groupIdentifier) in the response.'
      - schema:
          type: boolean
        name: attributeDescription
        in: query
        required: false
        description: 'If true, includes attribute descriptions in the response facts.'
      - schema:
          type: boolean
        name: filterFacts
        in: query
        required: false
        description: 'If true and masks are being resolved (via `maskType` or `maskTag`), only facts that have at least one matching mask are kept in the response. Facts without matching masks are removed. Has no effect when neither `maskType` nor `maskTag` is provided.'
    get:
      summary: Get product details (bulk)
      x-slug: /api/platform-api/products/get-multiple-by-sku
      tags:
        - Product Data
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"products\": [\r\n        {\r\n            \"id\": 241659429,\r\n            \"identifier\": \"IRB-50920\",\r\n            \"groupId\": \"IRB-50920\",\r\n            \"name\": \"Laptop AH\",\r\n            \"link\": \"www.myshop.com/product/IRB-50920\",\r\n            \"images\": [\r\n                {\r\n                    \"url\": \"www.myshop.com/product/IRB-50920/img.jpg\",\r\n                    \"type\": \"SMALL\"\r\n                }\r\n            ],\r\n            \"categories\": [\r\n                {\r\n                    \"path\": [\r\n                        \"Laptops\"\r\n                    ],\r\n                    \"categoryId\": 291156242\r\n                }\r\n            ],\r\n            \"facts\": [\r\n                {\r\n                    \"attributeId\": 288188589,\r\n                    \"attribute\": \"Brand\",\r\n                    \"valueId\": 292189243,\r\n                    \"value\": \"BrandW\",\r\n                    \"type\": \"TEXT_ATTRIBUTE\"\r\n                }\r\n            ],\r\n            \"lastUpdateTs\": 1745928435738\r\n        },\r\n        {\r\n            \"id\": 241659430,\r\n            \"identifier\": \"IRB-50921\",\r\n            \"groupId\": \"IRB-50921\",\r\n            \"name\": \"Laptop BX\",\r\n            \"link\": \"www.myshop.com/product/IRB-50921\",\r\n            \"images\": [\r\n                {\r\n                    \"url\": \"www.myshop.com/product/IRB-50921/img.jpg\",\r\n                    \"type\": \"SMALL\"\r\n                }\r\n            ],\r\n            \"categories\": [\r\n                {\r\n                    \"path\": [\r\n                        \"Laptops\"\r\n                    ],\r\n                    \"categoryId\": 291156243\r\n                }\r\n            ],\r\n            \"facts\": [\r\n                {\r\n                    \"attributeId\": 288188589,\r\n                    \"attribute\": \"Brand\",\r\n                    \"valueId\": 292189244,\r\n                    \"value\": \"BrandX\",\r\n                    \"type\": \"TEXT_ATTRIBUTE\"\r\n                }\r\n            ],\r\n            \"lastUpdateTs\": 1745928435740\r\n        }\r\n    ]\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      operationId: get-multiple-products-by-sku
      description: |-
        Returns detailed product information for multiple products at once. Pass product identifiers as a JSON array in the `identifiers` query parameter.

        This endpoint returns the same product structure as the single-product endpoint but wrapped in a `products` array.

        Example request:

        ```
        GET https://api.data.zoovu.com/product-service/products-by-sku?projectId=12345&identifiers=["PRD-001","PRD-002"]
        Authorization: Bearer YOUR_KEY
        ```
      security:
        - apiKeyHeader: []
  '/product-service/products':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
      - schema:
          type: string
        name: taskId
        description: the task ID returned by a product upload or update operation
        in: query
        required: true
      - schema:
          type: integer
        name: offset
        description: pagination offset
        in: query
      - schema:
          type: integer
        name: limit
        description: number of products to return
        in: query
    get:
      summary: Get products by task ID
      tags:
        - Product Data
      operationId: get-products-by-task-id
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  products:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        identifier:
                          type: string
                        groupId:
                          type: string
                        name:
                          type: string
                        link:
                          type: string
                        images:
                          type: array
                          items:
                            type: object
                            properties:
                              url:
                                type: string
                              type:
                                type: string
                        categories:
                          type: array
                          items:
                            type: object
                            properties:
                              path:
                                type: array
                                items:
                                  type: string
                              categoryId:
                                type: integer
                        facts:
                          type: array
                          items:
                            type: object
                            properties:
                              attributeId:
                                type: integer
                              attribute:
                                type: string
                              valueId:
                                type: integer
                              value:
                                type: string
                              type:
                                type: string
                              unit:
                                type: string
                              settings:
                                type: array
                                items:
                                  type: string
                        lastUpdateTs:
                          type: integer
              example:
                products:
                  - id: 70089885
                    identifier: 442314323853-01
                    groupId: 4488AA-01
                    name: example Gen Complete
                    link: 'https://www.example.com/example-gen5detect-iron-purple'
                    images:
                      - url: 'https://example-h.assetsadobe2.com/is/image/content/dam/example/Purple_tool.png?scl=1&fmt=png-alpha'
                        type: LARGE
                    categories:
                      - path:
                          - floorcare
                        categoryId: 3255111
                    facts:
                      - attributeId: 3255136
                        attribute: max_run_time
                        valueId: 265034544
                        value: Up to 70 minutes
                        type: TEXT_ATTRIBUTE
                        settings: []
                      - attributeId: 259604304
                        attribute: Catalog 1
                        value: 'TRUE'
                        type: BOOLEAN_ATTRIBUTE
                        settings: []
                    lastUpdateTs: 1710261266235
        '401':
          description: Unauthorized
        '404':
          description: Not Found
      description: |-
        Retrieve product data for multiple products associated with a specific task ID. Use the `offset` and `limit` parameters for pagination.

        The task ID is returned by product upload or update operations (e.g., batch upload, incremental update).
  /projects:
    get:
      summary: List projects
      description: 'Returns all existing projects within your account (defined by your API key in authorization header). If you have set up tags in the [Data Platform](https://data.zoovu.com/projects), you can use the `tags` parameter to filter your projects by tags.'
      security:
        - apiKeyHeader: []
      tags:
        - Product Data
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n  \"status\": \"success\",\r\n  \"data\": {\r\n    \"projects\": [\r\n      {\r\n        \"id\": 10001,\r\n        \"name\": \"Sample Account 1\",\r\n        \"project-group-id\": 20001,\r\n        \"project-group-name\": \"Sample Group 1\",\r\n        \"locale\": \"en-US\",\r\n        \"language\": \"en\",\r\n        \"country\": \"US\",\r\n        \"tags\": [\"example\", \"demo\"]\r\n      },\r\n      {\r\n        \"id\": 10002,\r\n        \"name\": \"Sample Account 2\",\r\n        \"project-group-id\": 20002,\r\n        \"project-group-name\": \"Sample Group 2\",\r\n        \"locale\": \"de-DE\",\r\n        \"language\": \"de\",\r\n        \"country\": \"DE\",\r\n        \"tags\": []\r\n      }\r\n    ]\r\n  }\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      projects:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            project-group-id:
                              type: integer
                            project-group-name:
                              type: string
                            locale:
                              type: string
                            language:
                              type: string
                            country:
                              type: string
                            tags:
                              type: array
                              items:
                                type: string
                x-examples:
                  Example 1:
                    status: success
                    data:
                      projects:
                        - id: 10001
                          name: Sample Account 1
                          project-group-id: 20001
                          project-group-name: Sample Group 1
                          locale: en-US
                          language: en
                          country: US
                          tags:
                            - example
                            - demo
                        - id: 10002
                          name: Sample Account 2
                          project-group-id: 20002
                          project-group-name: Sample Group 2
                          locale: de-DE
                          language: de
                          country: DE
                          tags: []
        '401':
          description: Unauthorized
      operationId: list-projects
      x-stoplight:
        id: hchywc7fzrhr8
      parameters:
        - schema:
            type: string
          in: query
          name: tags
          description: 'an array of tag names, e.g. ["us_sale_channel", "us_staging"]'
          required: false
  '/search':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    post:
      summary: Search products and content (POST)
      tags:
        - Product Search
      operationId: search-products-and-content
      security: []
      responses:
        '200':
          description: OK - see response examples below for different scenarios (products with filters, no results, banners/custom results, products with content).
          content:
            application/json:
              examples:
                Products with filters:
                  value:
                    searchResults:
                      - type: products
                        name: Products
                        totalResults: 5
                        totalResultsVariants: 5
                        totalResultsHead: 5
                        totalResultsHeadVariants: 5
                        results:
                          - - identifier: 'PRD-001'
                              groupId: 'PRD-001'
                              sxId: 100001
                              dataPoints:
                                - id: 1001
                                  conceptIdName: PRICE
                                  key: Price
                                  type: PASS_ON
                                  value: '49.99 $'
                                  parsedValue: 49.99
                                  unit: $
                                - id: 1002
                                  conceptIdName: CATEGORY
                                  key: Category
                                  type: PASS_ON
                                  value: Shoes
                                  isCategory: true
                                - id: 1001
                                  conceptIdName: PRICE
                                  key: Price
                                  type: FILTER
                                  parsedValue: 49.99
                                  value: '49.99 $'
                                  matched: true
                                - id: 1003
                                  conceptIdName: MATERIAL
                                  key: Material
                                  value: Leather
                                  show: true
                                  matched: true
                                  type: FILTER
                              image: 'https://www.example.com/images/prd-001.jpg'
                              name: Running Shoe Pro
                              images:
                                - type: ALTERNATIVE
                                  url: 'https://www.example.com/images/prd-001.jpg'
                              link: 'https://www.example.com/products/prd-001'
                              resultSet: null
                              head: true
                              relevance: 1000000
                    totalResults: 5
                    interpretedQuery:
                      matchSources: []
                      category: shoes
                      categoryId: 2001
                      normalizedCategory: ROOT/Shoes
                      categorySource: CUSTOMER
                      corrected: shoes
                      queryWasCorrected: false
                      original: shoes
                      intentMatched: false
                      confidence: 2
                      tags: []
                      resultSetType: USER_QUERY
                      filterMatchType: FULL_FILTER_MATCH
                    relatedQueries: []
                    showAllResults: false
                    suggestedFilters: null
                    answerText: null
                    offset: 0
                    limit: 20
                    activeSortingOption:
                      key: 1001
                      direction: ASC
                      name: Price (low to high)
                    sortingOptions:
                      - name: Price (low to high)
                        conceptIdName: PRICE
                        key: '1001'
                        type: ATTRIBUTE
                        sort: ASC
                      - name: Price (high to low)
                        conceptIdName: PRICE
                        key: '1001'
                        type: ATTRIBUTE
                        sort: DESC
                    activeFilterOptions:
                      - name: Price
                        key: '1001'
                        min: 20.0
                        max: 100.0
                        id: 1001
                        conceptIdName: PRICE
                      - name: Material
                        key: '1003'
                        values:
                          - value: MATERIAL_#_LEATHER
                            key: '1010'
                            name: Leather
                            conceptIdName: MATERIAL_#_LEATHER
                            id: 1010
                        id: 1003
                        conceptIdName: MATERIAL
                    activePreSetFilterOptions: []
                    activeSxFilterOptions: []
                    activeGuidedQuestions: []
                    filterGroups:
                      - name: default
                        filterOptions:
                          - '2001'
                          - '1004'
                          - '1001'
                          - '1003'
                    filterOptions:
                      - key: '2001'
                        name: Category
                        conceptIdName: CATEGORY
                        type: TREE
                        semanticLevel: 1
                        visible: true
                        categories:
                          - conceptId: 2002
                            key: '2002'
                            viewName: Shoes
                            name: Shoes
                            value: ROOT/Shoes
                            conceptIdName: ROOT/Shoes
                            count: 5
                            image: 'https://www.example.com/images/cat-shoes.jpg'
                            children:
                              - conceptId: 2003
                                key: '2003'
                                viewName: Running
                                name: Running
                                value: ROOT/Shoes/Running
                                conceptIdName: ROOT/Shoes/Running
                                count: 3
                                children: []
                        totalCategories: 2
                      - key: '1004'
                        name: Brand
                        conceptIdName: BRAND
                        type: COLLECTION
                        semanticLevel: 1
                        visible: true
                        values:
                          - key: 1011
                            name: BrandA
                            conceptIdName: BRAND_#_BRANDA
                            value: BRAND_#_BRANDA
                            count: 3
                          - key: 1012
                            name: BrandB
                            conceptIdName: BRAND_#_BRANDB
                            value: BRAND_#_BRANDB
                            count: 2
                        count: 5
                      - key: '1001'
                        name: Price
                        conceptIdName: PRICE
                        type: RANGE
                        semanticLevel: 1
                        visible: true
                        min: 29.99
                        max: 149.99
                        counts:
                          '29.99': 1
                          '49.99': 2
                          '89.99': 1
                          '149.99': 1
                        count: 5
                        unit: $
                        fractionalDigits: 2
                      - key: '1003'
                        name: Material
                        conceptIdName: MATERIAL
                        type: COLLECTION
                        semanticLevel: 1
                        visible: true
                        values:
                          - key: 1010
                            name: Leather
                            conceptIdName: MATERIAL_#_LEATHER
                            value: MATERIAL_#_LEATHER
                            count: 3
                          - key: 1013
                            name: Synthetic
                            conceptIdName: MATERIAL_#_SYNTHETIC
                            value: MATERIAL_#_SYNTHETIC
                            count: 2
                        count: 5
                    sxFilterOptions: []
                    filterMapping:
                      Products:
                        - '2001'
                        - '1004'
                        - '1001'
                        - '1003'
                      _: []
                    activeRanking: ZOOVU
                No results:
                  value:
                    searchResults:
                      - type: products
                        name: Products
                        totalResults: 0
                        totalResultsVariants: 0
                        totalResultsHead: 0
                        totalResultsHeadVariants: 0
                        results: []
                    totalResults: 0
                    interpretedQuery:
                      matchSources: []
                      category: null
                      categoryId: null
                      normalizedCategory: null
                      categorySource: ZOOVU
                      corrected: xyznonexistent
                      queryWasCorrected: false
                      original: xyznonexistent
                      intentMatched: false
                      confidence: 2
                      tags: []
                      resultSetType: USER_QUERY
                      filterMatchType: FULL_FILTER_MATCH
                    relatedQueries: []
                    showAllResults: true
                    suggestedFilters: null
                    answerText: We could not find any matching products.
                    offset: 0
                    limit: 20
                    activeSortingOption: {}
                    sortingOptions: []
                    activeFilterOptions: []
                    activePreSetFilterOptions: []
                    activeSxFilterOptions: []
                    activeGuidedQuestions: []
                    filterGroups: []
                    filterOptions: []
                    sxFilterOptions: []
                    filterMapping:
                      Products: []
                      _: []
                    activeRanking: ZOOVU
                With banners and custom results:
                  value:
                    searchResults:
                      - type: products
                        name: Products
                        totalResults: 3
                        totalResultsVariants: 1
                        totalResultsHead: 3
                        totalResultsHeadVariants: 1
                        results:
                          - - type: HTML
                              link: 'https://www.example.com/promo'
                              name: Spring Sale
                              content: '<p>Spring Sale - 20% off!</p>'
                              image: 'https://www.example.com/images/spring-sale.jpg'
                              dataPoints: []
                              resultSet: 0
                          - - type: custom
                              html: '<div><p>Free shipping on orders over $50</p></div>'
                              suggestionHtml: ''
                              resultSet: 0
                          - - identifier: 'PRD-001'
                              groupId: 'PRD-001'
                              sxId: 100001
                              dataPoints:
                                - id: 1001
                                  conceptIdName: PRICE
                                  key: Price
                                  type: PASS_ON
                                  value: '329.00 $'
                                  parsedValue: 329.0
                                  unit: $
                              image: 'https://www.example.com/images/prd-001.jpg'
                              name: Product Example
                              images:
                                - type: ALTERNATIVE
                                  url: 'https://www.example.com/images/prd-001.jpg'
                              link: 'https://www.example.com/products/prd-001'
                              resultSet: null
                              head: true
                              relevance: 1000000
                      - type: all
                        name: All Results
                        totalResults: 3
                        placements:
                          - type: HTML
                            position: 0
                            link: 'https://www.example.com/promo'
                            name: Spring Sale
                            content: 'Spring Sale - 20% off!'
                            image: 'https://www.example.com/images/spring-sale.jpg'
                            dataPoints: []
                          - type: custom
                            position: 1
                            html: '<div><p>Free shipping on orders over $50</p></div>'
                            suggestionHtml: ''
                          - type: PRODUCT
                            position: 2
                            id: 'PRD-001'
                    totalResults: 3
                    interpretedQuery:
                      matchSources: []
                      queryIntent:
                        type: DEFINITION
                      corrected: laptop
                      queryWasCorrected: false
                      original: laptop
                      intentMatched: true
                      confidence: 2
                      tags: []
                      resultSetType: USER_QUERY
                      filterMatchType: FULL_FILTER_MATCH
                    showAllResults: true
                    offset: 0
                    limit: 20
                    activeSortingOption: {}
                    sortingOptions: []
                    matchedIntentId: 12345
                    banner: '<div><p>Free shipping on orders over $50</p></div>'
                    activeFilterOptions: []
                    activePreSetFilterOptions: []
                    activeGuidedQuestions: []
                    filterGroups: []
                    filterOptions: []
                    sxFilterOptions: []
                    filterMapping:
                      Products: []
                      _: []
                    activeRanking: ZOOVU
                Products and content results:
                  value:
                    searchResults:
                      - type: products
                        name: Products
                        totalResults: 2
                        totalResultsVariants: 2
                        totalResultsHead: 2
                        totalResultsHeadVariants: 2
                        results:
                          - - identifier: 'PRD-001'
                              groupId: 'PRD-001'
                              sxId: 100001
                              relationTypes:
                                tags:
                                  - tag: you might also like
                                    relations:
                                      - name: Accessories
                                        id: 39
                                        matchType: FIRST_WAY
                                        localization:
                                          names: []
                                        exists: true
                              dataPoints:
                                - id: 1001
                                  conceptIdName: PRICE
                                  key: Price
                                  type: PASS_ON
                                  value: '$49.99'
                                  parsedValue: 49.99
                                  unit: $
                                - id: 1002
                                  conceptIdName: CATEGORY
                                  key: Category
                                  type: PASS_ON
                                  value: Dresses
                                  isCategory: true
                              image: 'https://www.example.com/images/prd-001.jpg'
                              name: Summer Dress
                              images:
                                - type: ALTERNATIVE
                                  url: 'https://www.example.com/images/prd-001.jpg'
                              link: 'https://www.example.com/products/prd-001'
                              resultSet: null
                              head: true
                              relevance: 1000000
                      - type: custom
                        name: Blog
                        totalResults: 1
                        results:
                          - name: Summer Fashion Guide
                            image: 'https://www.example.com/images/blog-summer.jpg'
                            link: 'https://www.example.com/blog/summer-fashion'
                            type: HTML
                            relevance: 16.5
                            content: '<span class="z-search-highlight">Dress</span> up for the season with our top picks.'
                            images: []
                            dataPoints:
                              - show: true
                                value: 'June 15, 2025'
                                key: Published date
                      - type: categories
                        name: Categories
                        totalResults: 1
                        results:
                          - image: 'https://www.example.com/images/cat-dresses.jpg'
                            link: 'https://www.example.com/categories/dresses'
                            name: Dresses
                    totalResults: 3
                    interpretedQuery:
                      matchSources: []
                      category: dress
                      categoryId: 2001
                      normalizedCategory: DRESS
                      categorySource: ZOOVU
                      corrected: dress
                      queryWasCorrected: false
                      original: dress
                      intentMatched: false
                      confidence: 2
                      tags: []
                      resultSetType: USER_QUERY
                      filterMatchType: FULL_FILTER_MATCH
                    relatedQueries: []
                    showAllResults: false
                    answerText: 'We found <span class="sx-highlight">2 dresses</span> for you.'
                    offset: 0
                    limit: 20
                    activeSortingOption: {}
                    sortingOptions: []
                    activeFilterOptions: []
                    activePreSetFilterOptions: []
                    activeGuidedQuestions: []
                    filterGroups: []
                    filterOptions:
                      - key: '1001'
                        name: Price
                        conceptIdName: PRICE
                        type: RANGE
                        semanticLevel: 1
                        visible: true
                        min: 36.99
                        max: 49.99
                        counts:
                          '36.99': 1
                          '49.99': 1
                        count: 2
                        unit: $
                        fractionalDigits: 2
                    sxFilterOptions: []
                    filterMapping:
                      Products:
                        - '1001'
                      Blog: []
                      _: []
                    activeRanking: ZOOVU
              schema:
                type: object
                properties:
                  searchResults:
                    type: array
                    description: Contains all search results grouped by type
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: 'The type of search results, e.g. products or custom (for content pages)'
                        name:
                          type: string
                          description: 'the name of the result group, e.g. Products or Blog'
                        totalResults:
                          type: integer
                          description: Total number of results (per result group)
                        totalResultsVariants:
                          type: integer
                          description: Total number of variant SKUs in the result set
                        totalResultsHead:
                          type: integer
                          description: The number of head (main) products displayed at the top of the search result set.
                        totalResultsHeadVariants:
                          type: integer
                          description: Total number of variant SKUs in the head (main) product result set
                        results:
                          type: array
                          description: |-
                            An array of search results, where each item may represent a group of variants, an individual product, or a custom result.

                            Custom results (banners and custom HTML results) can be configured in [Result Manager > Result Mappings](https://search.zoovu.com/result-manager/mappings). See the [documentation](https://docs.zoovu.com/search-studio/search-results/search-settings/customize-search-results) for details.

                            Result items have a `type` field that indicates the kind of result:
                            - No `type` field or absent — a regular product result.
                            - `"HTML"` — a custom result with `name`, `link`, `content` (HTML), `image`, and `dataPoints`.
                            - `"custom"` — a custom result with `html` and `suggestionHtml` fields containing raw HTML.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: 'The type of result item. Regular products do not have this field. Custom results have type `HTML` or `custom`.'
                                enum:
                                  - HTML
                                  - custom
                              identifier:
                                type: string
                                description: your internally used product ID
                              groupId:
                                type: string
                                description: an identifier used to group variants of the same product
                              dataPoints:
                                type: array
                                description: An array of product attributes
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: integer
                                      description: The concept ID
                                    conceptIdName:
                                      type: string
                                      description: The concept identifier
                                    key:
                                      type: string
                                      description: The view name for the attribute
                                    type:
                                      type: string
                                      enum:
                                        - PASS_ON
                                        - FILTER
                                        - MAPPING_FILTER
                                        - GUIDED_QUESTION
                                        - SORTING
                                        - BIAS
                                      description: |-
                                        The context in which this data point appears:
                                        - `PASS_ON` — attribute included via a search results attribute group (mask).
                                        - `FILTER` — attribute value that matched an active user filter.
                                        - `MAPPING_FILTER` — attribute value that matched a non-user (system/mapping) filter.
                                        - `GUIDED_QUESTION` — attribute value that matched an active guided question answer.
                                        - `SORTING` — attribute used for sorting/ranking the results.
                                        - `BIAS` — attribute used as a ranking bias.
                                        A single attribute can appear multiple times with different types.
                                    value:
                                      type: string
                                      description: 'the attribute value (e.g., for Price this will be the numeric value including the unit)'
                                    parsedValue:
                                      type: number
                                      description: A numeric value that removes the need for frontend developers to parse numbers from the string value.
                                    isCategory:
                                      type: boolean
                                      description: Indicates that this is a category attribute.
                                    unit:
                                      type: string
                                      description: 'The unit for numeric data (e.g., $ for Price)'
                              image:
                                type: string
                                description: URL to the product image
                              name:
                                type: string
                                description: the product name
                              images:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      description: type will be ALTERNATIVE
                                    url:
                                      type: string
                                      description: URL(s) to additional images
                              link:
                                type: string
                                description: URL to the product detail page
                              resultSet:
                                nullable: true
                              head:
                                type: boolean
                                description: Whether the product is a head (main) product
                              relevance:
                                type: integer
                                description: Used to rank products
                              content:
                                type: string
                                description: 'HTML content to display (for `HTML` type custom results only)'
                              html:
                                type: string
                                description: 'Raw HTML content (for `custom` type results only)'
                              suggestionHtml:
                                type: string
                                description: 'Suggestion HTML content (for `custom` type results only)'
                        placements:
                          type: array
                          description: |-
                            An array of products/content that have been pinned to specific positions in the Result Manager in the All Results tab.

                            Placement items have a `type` field: `"PRODUCT"` for products, `"HTML"` for custom HTML results, or `"custom"` for custom results.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: 'The type of placement: `PRODUCT`, `HTML`, or `custom`.'
                                enum:
                                  - PRODUCT
                                  - HTML
                                  - custom
                              position:
                                type: integer
                                description: The 0-based position in the result list
                              id:
                                type: string
                                description: 'Product identifier (for `PRODUCT` type placements only)'
                              link:
                                type: string
                                description: 'URL link (for `HTML` type placements only)'
                              name:
                                type: string
                                description: 'Display name (for `HTML` type placements only)'
                              content:
                                type: string
                                description: 'HTML content (for `HTML` type placements only)'
                              image:
                                type: string
                                description: 'Image URL (for `HTML` type placements only)'
                              dataPoints:
                                type: array
                                description: 'Data points (for `HTML` type placements only)'
                                items:
                                  type: object
                              html:
                                type: string
                                description: 'Raw HTML content (for `custom` type placements only)'
                              suggestionHtml:
                                type: string
                                description: 'Suggestion HTML content (for `custom` type placements only)'
                  totalResults:
                    type: integer
                    description: The total number of search results across all groups
                  interpretedQuery:
                    type: object
                    description: Parsed interpretation of the user's search query.
                    properties:
                      matchSources:
                        type: array
                        items:
                          type: object
                      queryIntent:
                        type: object
                        description: Indicates a result mapping exists.
                        properties:
                          type:
                            type: string
                            description: Result mappings with the action "search and customize results" have the type DEFINITION.
                      category:
                        type: string
                      categoryId:
                        type: integer
                      normalizedCategory:
                        type: string
                      categorySource:
                        type: string
                      corrected:
                        type: string
                        description: 'If spelling correction was applied, the corrected spelling will be provided here.'
                      queryWasCorrected:
                        type: boolean
                        description: 'If set to true, this means the automatic spellcheck corrected the spelling.'
                      original:
                        type: string
                        description: 'The original, uncorrected search query.'
                      intentMatched:
                        type: boolean
                        description: Indicates a result mapping was matched for this query.
                      confidence:
                        type: integer
                      tags:
                        type: array
                        items:
                          type: object
                      resultSetType:
                        type: string
                  relatedQueries:
                    type: array
                    description: 'If you connect the necessary [tracking](https://docs.zoovu.com/search-studio/insights-and-reporting/track-external-interfaces/), you will receive related queries in the search response.'
                    items:
                      type: object
                  showAllResults:
                    type: boolean
                    description: Indicates whether the response contains the All Results group.
                  suggestedFilters:
                    nullable: true
                  answerText:
                    description: A sentence explaining the search results.
                    nullable: true
                  offset:
                    type: integer
                    description: The offset provided in the search request.
                  limit:
                    type: integer
                    description: The limit provided in the search request.
                  activeSortingOption:
                    type: object
                    description: The currently applied sorting option. Empty object if no sorting is active.
                    properties:
                      key:
                        type: integer
                        description: The concept ID of the applied sorting attribute.
                      direction:
                        type: string
                        enum:
                          - ASC
                          - DESC
                        description: The sorting direction.
                      name:
                        type: string
                        description: The display name of the sorting option.
                  sortingOptions:
                    type: array
                    description: Available sorting options configured in Search Studio.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 'Display name (e.g., "Price (Low to High)")'
                        conceptIdName:
                          type: string
                          description: The concept identifier used for sorting
                        key:
                          type: string
                          description: The concept ID as a string key
                        type:
                          type: string
                          description: 'Sorting type (e.g., ATTRIBUTE)'
                        sort:
                          type: string
                          enum:
                            - ASC
                            - DESC
                          description: Sort direction
                  matchedIntentId:
                    type: integer
                  activeFilterOptions:
                    type: array
                    description: Filters currently applied to the search results.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 'Display name of the filter — alternative to `conceptIdName` for identifying the filter attribute'
                        key:
                          type: string
                          description: 'The concept ID as a string key — alternative to `conceptIdName` for identifying the filter attribute'
                        id:
                          type: integer
                          description: 'The concept ID — alternative to `conceptIdName` for identifying the filter attribute'
                        conceptIdName:
                          type: string
                          description: 'The concept identifier (recommended way to identify the filter attribute)'
                        min:
                          type: number
                          description: 'For RANGE filters: the active minimum value'
                        max:
                          type: number
                          description: 'For RANGE filters: the active maximum value'
                        values:
                          type: array
                          description: 'For COLLECTION/COLOR filters: the selected filter values'
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                              key:
                                type: string
                              name:
                                type: string
                              conceptIdName:
                                type: string
                              id:
                                type: integer
                  activePreSetFilterOptions:
                    type: array
                    description: Pre-set filters currently applied to the search. These are server-side filters that are not visible to the end user.
                    items:
                      type: object
                  activeGuidedQuestions:
                    type: array
                    description: Guided question answers currently active in the session.
                    items:
                      type: object
                      properties:
                        questionId:
                          type: integer
                          description: the ID of the guided question
                        answerId:
                          type: integer
                          description: the ID of the selected answer (0-based index)
                        name:
                          type: string
                          description: the display name of the selected answer
                  filterGroups:
                    type: array
                    items:
                      type: object
                  filterOptions:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        name:
                          type: string
                        conceptIdName:
                          type: string
                        type:
                          type: string
                        semanticLevel:
                          type: integer
                        visible:
                          type: boolean
                        values:
                          type: array
                          description: 'Filter option values (for COLLECTION and COLOR type filters)'
                          items:
                            type: object
                            properties:
                              key:
                                type: integer
                              name:
                                type: string
                              conceptIdName:
                                type: string
                              value:
                                type: string
                              count:
                                type: integer
                              color:
                                type: string
                                description: 'Hex color code (for COLOR type filters only, e.g., "#2652a7")'
                        categories:
                          type: array
                          description: 'Category tree (for TREE type filters only)'
                          items:
                            type: object
                            properties:
                              conceptId:
                                type: integer
                              key:
                                type: string
                              viewName:
                                type: string
                                description: the localized display name
                              name:
                                type: string
                              value:
                                type: string
                                description: 'the full category path (e.g., "ROOT/Clothing/Dresses")'
                              conceptIdName:
                                type: string
                              count:
                                type: integer
                              image:
                                type: string
                                description: URL to a representative product image for this category
                              url:
                                type: object
                                description: link associated with this category
                                properties:
                                  source:
                                    type: string
                                  link:
                                    type: string
                              conceptImage:
                                type: object
                                nullable: true
                                description: configured category image
                                properties:
                                  source:
                                    type: string
                                  link:
                                    type: string
                              children:
                                type: array
                                description: nested child categories (same structure, recursive)
                                items:
                                  type: object
                        totalCategories:
                          type: integer
                          description: 'Total number of categories across all levels (for TREE type filters only)'
                        count:
                          type: integer
                        min:
                          type: number
                        max:
                          type: number
                        counts:
                          type: object
                        unit:
                          type: string
                        fractionalDigits:
                          type: integer
                  filterMapping:
                    type: object
                    properties:
                      Products:
                        type: array
                        items:
                          type: string
                      _:
                        type: array
                        items:
                          type: object
                      Other:
                        type: array
                        items:
                          type: object
                  activeRanking:
                    type: string
                  banner:
                    type: string
                    nullable: true
                    description: 'HTML content for a promotional banner, if configured via [Result Manager > Result Mappings](https://search.zoovu.com/result-manager/mappings). See the [documentation](https://docs.zoovu.com/search-studio/search-results/search-settings/customize-search-results#add-promotional-banners) for details.'
        '404':
          description: Not found
      x-stoplight:
        id: 8f9gayrajuw3f
      description: |-
        This endpoint lets you search for products (and content, if applicable) matching your query.

        Please make sure to always attach a sessionId to the request body.

        Additionally, make sure to forward the client IP address via an HTTP header called HTTP_CLIENT_IP - this makes it possible to set a limit for queries per IP per hour to prevent abuse.

        **Navigation queries:** To use Zoovu for category navigation or landing pages, use the query format `_#CategoryLevel1#CategoryLevel2#...`. For example, `_#Electronics#Phones#Smartphones` navigates to the Smartphones category. Category levels are separated by `#` and the query always starts with `_#`.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                query: laptop
                offset: 0
                limit: 100
                userGroup: shop_germany
                sessionId: d9f1e8c3b4a6
                includeContentGroups:
                  - Products
                excludeContentGroups:
                  - Blog
                catalogId: 4565
                autocorrect: true
                filters:
                  - name: Brand
                    type: products
                    values:
                      - name: BrandABC
                preSetFilters:
                  - name: IS_ONLINE
                    booleanValue: true
                  - name: Category
                    without: true
                    values:
                      - value: 'Online|catalog|cat_hidden'
                includeTags:
                  - tag: Compatible
                    limitPerRelation: 4
                highlightQueryTerms: true
                sort: Price (low to high)
                queryTag: app
                activeGuidedQuestions:
                  - questionId: 27581
                    answerId: 0
                    name: 'Budget: Under $30'
                  - questionId: 27582
                    answerId: 0
                    name: Organic Cotton
                maskType: MINI_PDP
              properties:
                query:
                  type: string
                  description: |-
                    a search term or navigational query

                    To use Zoovu for your category navigation or landing pages, you need to use a special query format as described in [this guide](https://docs.zoovu.com/api/guides/platform/navigational-queries).
                offset:
                  type: integer
                  description: how many results to skip (used for pagination)
                limit:
                  type: integer
                  description: how many results to return (ranging from 0 to 1000)
                userGroup:
                  type: string
                  description: 'if you defined user groups when importing your product data, you can use this parameter to set the appropriate user group for the user currently searching. This ensures the search results will respect all user-group-specific rules. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
                sessionId:
                  type: string
                  description: a sessionId unique to the user
                includeContentGroups:
                  type: array
                  description: limits API response to these included result groups
                excludeContentGroups:
                  type: array
                  description: excludes these result groups from the API response
                catalogId:
                  type: integer
                  description: you can limit search results to any of your Data Platform catalogs by providing the catalogId. You can copy the catalogId from the three-dot menu to the right of each catalog.
                autocorrect:
                  type: boolean
                  description: You can turn autocorrection off by setting this parameter to false. This allows you to build Google-style SERPs that display the message "We searched for 'teacup'. Search for 'teecup' instead".
                filters:
                  type: array
                  description: |-
                    A URL-encoded JSON array containing filters for product search OR content search (NOT both at the same time). Supports filtering by name, conceptIdName (recommended), or database ID, with options for collection, range, boolean, and content filters.

                    Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting) for detailed syntax, examples, and additional filter options.
                  items:
                    $ref: '#/components/schemas/FilterObject'
                preSetFilters:
                  type: array
                  description: |-
                    Same JSON schema as `filters`, but applied server-side and invisible to the end user. Used to pre-filter the product catalog for a specific integration (e.g., showing only available products or excluding certain categories).

                    Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting#pre-set-filters) for details and examples.
                  items:
                    $ref: '#/components/schemas/FilterObject'
                includeTags:
                  type: string
                  description: |-
                    a JSON array of relation tag objects to resolve for each product in the results. Each object specifies a relation type (`tag`) and an optional `limitPerRelation`. The `tag` value corresponds to a relation type configured in [Relations](https://data.zoovu.com/relations). When provided, each product in the response includes a `relationTypes.tags` array with the matching relations.

                    Example: `[{"tag":"Compatible", "limitPerRelation":4}]`
                highlightQueryTerms:
                  type: boolean
                  description: 'if true, the query will be highlighted in the response whenever it occurs in the product title, description, etc.'
                sort:
                  type: string
                  description: 'a string containing the name of the sorting option from Search Studio, e.g., "Price (low to high)". Sorting options must be configured in Search Studio for this parameter to work.'
                sortComplex:
                  type: object
                  x-stoplight:
                    id: e9wkgasz99idp
                  description: |-
                    a URL-encoded JSON object containing the sorting information.

                    You can sort using concept ID
                    `{"key": "123421", "direction":"ASC"}`

                    or concept identifier/conceptIdName:
                    `{"conceptIdName": "PRICE", "direction":"ASC"}`

                    Finally, you can also sort by ranking strategy ID, which you can copy from the three-dot menu next to your [ranking strategy](https://search.zoovu.com/ranking-strategies):
                    `{"rankingStrategyId":"60fe8a94097548517a966752", "type":"STRATEGY"}`
                queryTag:
                  type: string
                  x-stoplight:
                    id: qtavg5mahwf04
                  description: 'A free-form query tag, used to tag your queries so that they can later be clustered in search analytics. An example might be tagging traffic from your app (queryTag=app) and webstore (queryTag=store) differently.'
                activeGuidedQuestions:
                  type: array
                  description: 'An array of guided question answers currently active in the session. Each entry contains the question ID, answer ID, and display name. The search results are refined based on these selections. Guided questions are configured in the [AI Guided Questions](https://data.zoovu.com/question-bank).'
                  items:
                    type: object
                    properties:
                      questionId:
                        type: integer
                        description: the ID of the guided question
                      answerId:
                        type: integer
                        description: the ID of the selected answer (0-based index)
                      name:
                        type: string
                        description: the display name of the selected answer
                  example:
                    - questionId: 27581
                      answerId: 0
                      name: 'Budget: Under $30'
                    - questionId: 27582
                      answerId: 0
                      name: Organic Cotton
                maskType:
                  type: string
                  enum:
                    - PIM
                    - MINI_PDP
                    - REFINEMENT
                    - ZOE
                    - PASS_ON
                    - PASS_ON_SUGGESTION
                    - ASSISTANT
                    - MCP
                    - RELATIONS
                  description: 'Filters the product data points in search results by mask type. Only attributes included in a mask of the specified type will appear in the product data points. Case-insensitive.'
      parameters:
        - schema:
            type: string
          in: header
          name: HTTP_CLIENT_IP
          description: Please include the client IP in the HTTP_CLIENT_IP header to enable rate limiting and prevent API abuse.
    get:
      summary: Search products and content (GET)
      tags:
        - Product Search
      operationId: search-products-and-content-get
      security: []
      responses:
        '200':
          description: OK - same response format as [POST /search](#operation/search-products-and-content)
          content:
            application/json:
              schema:
                type: object
                properties:
                  searchResults:
                    type: array
                    description: Contains all search results grouped by type
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: 'The type of search results, e.g. products or custom (for content pages)'
                        name:
                          type: string
                          description: 'the name of the result group, e.g. Products or Blog'
                        totalResults:
                          type: integer
                          description: Total number of results (per result group)
                        totalResultsVariants:
                          type: integer
                          description: Total number of variant SKUs in the result set
                        totalResultsHead:
                          type: integer
                          description: The number of head (main) products displayed at the top of the search result set.
                        totalResultsHeadVariants:
                          type: integer
                          description: Total number of variant SKUs in the head (main) product result set
                        results:
                          type: array
                          description: |-
                            An array of search results, where each item may represent a group of variants, an individual product, or a custom result.

                            Custom results (banners and custom HTML results) can be configured in [Result Manager > Result Mappings](https://search.zoovu.com/result-manager/mappings). See the [documentation](https://docs.zoovu.com/search-studio/search-results/search-settings/customize-search-results) for details.

                            Result items have a `type` field that indicates the kind of result:
                            - No `type` field or absent — a regular product result.
                            - `"HTML"` — a custom result with `name`, `link`, `content` (HTML), `image`, and `dataPoints`.
                            - `"custom"` — a custom result with `html` and `suggestionHtml` fields containing raw HTML.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: 'The type of result item. Regular products do not have this field. Custom results have type `HTML` or `custom`.'
                                enum:
                                  - HTML
                                  - custom
                              identifier:
                                type: string
                                description: your internally used product ID
                              groupId:
                                type: string
                                description: an identifier used to group variants of the same product
                              dataPoints:
                                type: array
                                description: An array of product attributes
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: integer
                                      description: The concept ID
                                    conceptIdName:
                                      type: string
                                      description: The concept identifier
                                    key:
                                      type: string
                                      description: The view name for the attribute
                                    type:
                                      type: string
                                      enum:
                                        - PASS_ON
                                        - FILTER
                                        - MAPPING_FILTER
                                        - GUIDED_QUESTION
                                        - SORTING
                                        - BIAS
                                      description: |-
                                        The context in which this data point appears:
                                        - `PASS_ON` — attribute included via a search results attribute group (mask).
                                        - `FILTER` — attribute value that matched an active user filter.
                                        - `MAPPING_FILTER` — attribute value that matched a non-user (system/mapping) filter.
                                        - `GUIDED_QUESTION` — attribute value that matched an active guided question answer.
                                        - `SORTING` — attribute used for sorting/ranking the results.
                                        - `BIAS` — attribute used as a ranking bias.
                                        A single attribute can appear multiple times with different types.
                                    value:
                                      type: string
                                      description: 'the attribute value (e.g., for Price this will be the numeric value including the unit)'
                                    parsedValue:
                                      type: number
                                      description: A numeric value that removes the need for frontend developers to parse numbers from the string value.
                                    isCategory:
                                      type: boolean
                                      description: Indicates that this is a category attribute.
                                    unit:
                                      type: string
                                      description: 'The unit for numeric data (e.g., $ for Price)'
                              image:
                                type: string
                                description: URL to the product image
                              name:
                                type: string
                                description: the product name
                              images:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    type:
                                      type: string
                                      description: type will be ALTERNATIVE
                                    url:
                                      type: string
                                      description: URL(s) to additional images
                              link:
                                type: string
                                description: URL to the product detail page
                              resultSet:
                                nullable: true
                              head:
                                type: boolean
                                description: Whether the product is a head (main) product
                              relevance:
                                type: integer
                                description: Used to rank products
                              content:
                                type: string
                                description: 'HTML content to display (for `HTML` type custom results only)'
                              html:
                                type: string
                                description: 'Raw HTML content (for `custom` type results only)'
                              suggestionHtml:
                                type: string
                                description: 'Suggestion HTML content (for `custom` type results only)'
                        placements:
                          type: array
                          description: |-
                            An array of products/content that have been pinned to specific positions in the Result Manager in the All Results tab.

                            Placement items have a `type` field: `"PRODUCT"` for products, `"HTML"` for custom HTML results, or `"custom"` for custom results.
                          items:
                            type: object
                            properties:
                              type:
                                type: string
                                description: 'The type of placement: `PRODUCT`, `HTML`, or `custom`.'
                                enum:
                                  - PRODUCT
                                  - HTML
                                  - custom
                              position:
                                type: integer
                                description: The 0-based position in the result list
                              id:
                                type: string
                                description: 'Product identifier (for `PRODUCT` type placements only)'
                              link:
                                type: string
                                description: 'URL link (for `HTML` type placements only)'
                              name:
                                type: string
                                description: 'Display name (for `HTML` type placements only)'
                              content:
                                type: string
                                description: 'HTML content (for `HTML` type placements only)'
                              image:
                                type: string
                                description: 'Image URL (for `HTML` type placements only)'
                              dataPoints:
                                type: array
                                description: 'Data points (for `HTML` type placements only)'
                                items:
                                  type: object
                              html:
                                type: string
                                description: 'Raw HTML content (for `custom` type placements only)'
                              suggestionHtml:
                                type: string
                                description: 'Suggestion HTML content (for `custom` type placements only)'
                  totalResults:
                    type: integer
                    description: The total number of search results across all groups
                  interpretedQuery:
                    type: object
                    description: Parsed interpretation of the user's search query.
                    properties:
                      matchSources:
                        type: array
                        items:
                          type: object
                      queryIntent:
                        type: object
                        description: Indicates a result mapping exists.
                        properties:
                          type:
                            type: string
                            description: Result mappings with the action "search and customize results" have the type DEFINITION.
                      category:
                        type: string
                      categoryId:
                        type: integer
                      normalizedCategory:
                        type: string
                      categorySource:
                        type: string
                      corrected:
                        type: string
                        description: 'If spelling correction was applied, the corrected spelling will be provided here.'
                      queryWasCorrected:
                        type: boolean
                        description: 'If set to true, this means the automatic spellcheck corrected the spelling.'
                      original:
                        type: string
                        description: 'The original, uncorrected search query.'
                      intentMatched:
                        type: boolean
                        description: Indicates a result mapping was matched for this query.
                      confidence:
                        type: integer
                      tags:
                        type: array
                        items:
                          type: object
                      resultSetType:
                        type: string
                  relatedQueries:
                    type: array
                    description: 'If you connect the necessary [tracking](https://docs.zoovu.com/search-studio/insights-and-reporting/track-external-interfaces/), you will receive related queries in the search response.'
                    items:
                      type: object
                  showAllResults:
                    type: boolean
                    description: Indicates whether the response contains the All Results group.
                  suggestedFilters:
                    nullable: true
                  answerText:
                    description: A sentence explaining the search results.
                    nullable: true
                  offset:
                    type: integer
                    description: The offset provided in the search request.
                  limit:
                    type: integer
                    description: The limit provided in the search request.
                  activeSortingOption:
                    type: object
                    description: The currently applied sorting option. Empty object if no sorting is active.
                    properties:
                      key:
                        type: integer
                        description: The concept ID of the applied sorting attribute.
                      direction:
                        type: string
                        enum:
                          - ASC
                          - DESC
                        description: The sorting direction.
                      name:
                        type: string
                        description: The display name of the sorting option.
                  sortingOptions:
                    type: array
                    description: Available sorting options configured in Search Studio.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 'Display name (e.g., "Price (Low to High)")'
                        conceptIdName:
                          type: string
                          description: The concept identifier used for sorting
                        key:
                          type: string
                          description: The concept ID as a string key
                        type:
                          type: string
                          description: 'Sorting type (e.g., ATTRIBUTE)'
                        sort:
                          type: string
                          enum:
                            - ASC
                            - DESC
                          description: Sort direction
                  matchedIntentId:
                    type: integer
                  activeFilterOptions:
                    type: array
                    description: Filters currently applied to the search results.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: 'Display name of the filter — alternative to `conceptIdName` for identifying the filter attribute'
                        key:
                          type: string
                          description: 'The concept ID as a string key — alternative to `conceptIdName` for identifying the filter attribute'
                        id:
                          type: integer
                          description: 'The concept ID — alternative to `conceptIdName` for identifying the filter attribute'
                        conceptIdName:
                          type: string
                          description: 'The concept identifier (recommended way to identify the filter attribute)'
                        min:
                          type: number
                          description: 'For RANGE filters: the active minimum value'
                        max:
                          type: number
                          description: 'For RANGE filters: the active maximum value'
                        values:
                          type: array
                          description: 'For COLLECTION/COLOR filters: the selected filter values'
                          items:
                            type: object
                            properties:
                              value:
                                type: string
                              key:
                                type: string
                              name:
                                type: string
                              conceptIdName:
                                type: string
                              id:
                                type: integer
                  activePreSetFilterOptions:
                    type: array
                    description: Pre-set filters currently applied to the search. These are server-side filters that are not visible to the end user.
                    items:
                      type: object
                  activeGuidedQuestions:
                    type: array
                    description: Guided question answers currently active in the session.
                    items:
                      type: object
                      properties:
                        questionId:
                          type: integer
                          description: the ID of the guided question
                        answerId:
                          type: integer
                          description: the ID of the selected answer (0-based index)
                        name:
                          type: string
                          description: the display name of the selected answer
                  filterGroups:
                    type: array
                    items:
                      type: object
                  filterOptions:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        name:
                          type: string
                        conceptIdName:
                          type: string
                        type:
                          type: string
                        semanticLevel:
                          type: integer
                        visible:
                          type: boolean
                        values:
                          type: array
                          description: 'Filter option values (for COLLECTION and COLOR type filters)'
                          items:
                            type: object
                            properties:
                              key:
                                type: integer
                              name:
                                type: string
                              conceptIdName:
                                type: string
                              value:
                                type: string
                              count:
                                type: integer
                              color:
                                type: string
                                description: 'Hex color code (for COLOR type filters only, e.g., "#2652a7")'
                        categories:
                          type: array
                          description: 'Category tree (for TREE type filters only)'
                          items:
                            type: object
                            properties:
                              conceptId:
                                type: integer
                              key:
                                type: string
                              viewName:
                                type: string
                                description: the localized display name
                              name:
                                type: string
                              value:
                                type: string
                                description: 'the full category path (e.g., "ROOT/Clothing/Dresses")'
                              conceptIdName:
                                type: string
                              count:
                                type: integer
                              image:
                                type: string
                                description: URL to a representative product image for this category
                              url:
                                type: object
                                description: link associated with this category
                                properties:
                                  source:
                                    type: string
                                  link:
                                    type: string
                              conceptImage:
                                type: object
                                nullable: true
                                description: configured category image
                                properties:
                                  source:
                                    type: string
                                  link:
                                    type: string
                              children:
                                type: array
                                description: nested child categories (same structure, recursive)
                                items:
                                  type: object
                        totalCategories:
                          type: integer
                          description: 'Total number of categories across all levels (for TREE type filters only)'
                        count:
                          type: integer
                        min:
                          type: number
                        max:
                          type: number
                        counts:
                          type: object
                        unit:
                          type: string
                        fractionalDigits:
                          type: integer
                  filterMapping:
                    type: object
                    properties:
                      Products:
                        type: array
                        items:
                          type: string
                      _:
                        type: array
                        items:
                          type: object
                      Other:
                        type: array
                        items:
                          type: object
                  activeRanking:
                    type: string
                  banner:
                    type: string
                    nullable: true
                    description: 'HTML content for a promotional banner, if configured via [Result Manager > Result Mappings](https://search.zoovu.com/result-manager/mappings). See the [documentation](https://docs.zoovu.com/search-studio/search-results/search-settings/customize-search-results#add-promotional-banners) for details.'
        '404':
          description: Not found
      x-stoplight:
        id: get-search-products
      description: |-
        Alternative GET endpoint for searching products and content. All parameters are passed as query parameters instead of a request body.

        Please make sure to always attach a sessionId to the request.

        Additionally, make sure to forward the client IP address via an HTTP header called HTTP_CLIENT_IP - this makes it possible to set a limit for queries per IP per hour to prevent abuse.

        **Navigation queries:** To use Zoovu for category navigation or landing pages, use the query format `_#CategoryLevel1#CategoryLevel2#...`. For example, `_#Electronics#Phones#Smartphones` navigates to the Smartphones category.
      parameters:
        - schema:
            type: integer
          in: query
          name: projectId
          description: your Data Platform project ID
          required: true
        - schema:
            type: string
          in: query
          name: query
          description: |-
            a search term or navigational query

            To use Zoovu for your category navigation or landing pages, you need to use a special query format as described in [this guide](https://docs.zoovu.com/api/guides/platform/navigational-queries).
          required: true
        - schema:
            type: integer
          in: query
          name: offset
          description: how many results to skip (used for pagination)
        - schema:
            type: integer
          in: query
          name: limit
          description: how many results to return (ranging from 0 to 1000)
        - schema:
            type: string
          in: query
          name: userGroup
          description: 'if you defined user groups when importing your product data, you can use this parameter to set the appropriate user group for the user currently searching. This ensures the search results will respect all user-group-specific rules. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
        - schema:
            type: string
          in: query
          name: sessionId
          description: a sessionId unique to the user
        - schema:
            type: string
          in: query
          name: includeContentGroups
          description: 'a URL-encoded JSON array that limits API response to these included result groups, e.g. `["Products"]`.'
        - schema:
            type: string
          in: query
          name: excludeContentGroups
          description: 'a URL-encoded JSON array that excludes these result groups from the API response, e.g. `["Blog"]`.'
        - schema:
            type: integer
          in: query
          name: catalogId
          description: you can limit search results to any of your Data Platform catalogs by providing the catalogId. You can copy the catalogId from the three-dot menu to the right of each catalog.
        - schema:
            type: boolean
          in: query
          name: autocorrect
          description: You can turn autocorrection off by setting this parameter to false. This allows you to build Google-style SERPs that display the message "We searched for 'teacup'. Search for 'teecup' instead".
        - schema:
            type: string
          in: query
          name: filters
          description: |-
            A URL-encoded JSON array containing filters for product search OR content search (NOT both at the same time). Supports filtering by name, conceptIdName (recommended), or database ID, with options for collection, range, boolean, and content filters.

            Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting) for detailed syntax, examples, and additional filter options.
        - schema:
            type: string
          in: query
          name: preSetFilters
          description: |-
            A URL-encoded JSON array. Same schema as `filters`, but applied server-side and invisible to the end user. Used to pre-filter the product catalog for a specific integration (e.g., showing only available products or excluding certain categories).

            Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting#pre-set-filters) for details and examples.
        - schema:
            type: string
          in: query
          name: includeTags
          description: |-
            a URL-encoded JSON array of relation tag objects to resolve for each product in the results. Each object specifies a relation type (`tag`) and an optional `limitPerRelation`. The `tag` value corresponds to a relation type configured in [Relations](https://data.zoovu.com/relations). When provided, each product in the response includes a `relationTypes.tags` array with the matching relations.

            Example: `[{"tag":"Compatible", "limitPerRelation":4}]`
        - schema:
            type: boolean
          in: query
          name: highlightQueryTerms
          description: 'if true, the query will be highlighted in the response whenever it occurs in the product title, description, etc.'
        - schema:
            type: string
          in: query
          name: sort
          description: 'a string containing the name of the sorting option from Search Studio, e.g., "Price (low to high)". Sorting options must be configured in Search Studio for this parameter to work.'
        - schema:
            type: string
          in: query
          name: sortComplex
          description: |-
            a URL-encoded JSON object containing the sorting information.

            You can sort using concept ID
            `{"key": "123421", "direction":"ASC"}`

            or concept identifier/conceptIdName:
            `{"conceptIdName": "PRICE", "direction":"ASC"}`

            Finally, you can also sort by ranking strategy ID, which you can copy from the three-dot menu next to your [ranking strategy](https://search.zoovu.com/ranking-strategies):
            `{"rankingStrategyId":"60fe8a94097548517a966752", "type":"STRATEGY"}`
        - schema:
            type: string
          in: query
          name: queryTag
          description: 'A free-form query tag, used to tag your queries so that they can later be clustered in search analytics. An example might be tagging traffic from your app (queryTag=app) and webstore (queryTag=store) differently.'
        - schema:
            type: string
          in: query
          name: activeGuidedQuestions
          description: 'a URL-encoded JSON array of guided question answers currently active in the session. Each entry contains the question ID, answer ID, and display name. The search results are refined based on these selections. Guided questions are configured in the [AI Guided Questions](https://data.zoovu.com/question-bank).'
          example: '[{"questionId":27581,"answerId":0,"name":"Budget: Under $30"},{"questionId":27582,"answerId":0,"name":"Organic Cotton"}]'
        - schema:
            type: string
            enum:
              - PIM
              - MINI_PDP
              - REFINEMENT
              - ZOE
              - PASS_ON
              - PASS_ON_SUGGESTION
              - ASSISTANT
              - MCP
              - RELATIONS
          in: query
          name: maskType
          description: 'Filters the product data points in search results by mask type. Only attributes included in a mask of the specified type will appear in the product data points. Case-insensitive.'
        - schema:
            type: string
          in: header
          name: HTTP_CLIENT_IP
          description: Please include the client IP in the HTTP_CLIENT_IP header to enable rate limiting and prevent API abuse.
  '/search/suggestions':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    get:
      summary: Get search suggestions
      security: []
      tags:
        - Product Search
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"searchResults\": [\r\n        {\r\n            \"type\": \"products\",\r\n            \"name\": \"Products\",\r\n            \"totalResults\": 1,\r\n            \"totalResultsVariants\": 5,\r\n            \"totalResultsHead\": 1,\r\n            \"totalResultsHeadVariants\": 5,\r\n            \"results\": [\r\n                [\r\n                    {\r\n                        \"identifier\": \"PRD-9876-RED44\",\r\n                        \"groupId\": \"9876\",\r\n                        \"sxId\": 240538696,\r\n                        \"dataPoints\": [],\r\n                        \"image\": \"www.myshop.com/product/9876-red44/img.jpg\",\r\n                        \"name\": \"Laptop 9876 Red\",\r\n                        \"images\": [\r\n                            {\r\n                                \"type\": \"ALTERNATIVE\",\r\n                                \"url\": \"www.myshop.com/product/9876-red44/img.jpg\"\r\n                            }\r\n                        ],\r\n                        \"link\": \"www.myshop.com/product/9876-red44\",\r\n                        \"resultSet\": null,\r\n                        \"head\": true,\r\n                        \"relevance\": 1000000\r\n                    }\r\n                ]\r\n            ]\r\n        },\r\n        {\r\n            \"type\": \"queries\",\r\n            \"name\": \"Suggestions\",\r\n            \"totalResults\": 3,\r\n            \"results\": [\r\n                {\r\n                    \"name\": \"laptops\"\r\n                },\r\n                {\r\n                    \"name\": \"laptops acer\"\r\n                },\r\n                {\r\n                    \"name\": \"laptops dell\"\r\n                }\r\n            ]\r\n        },\r\n        {\r\n            \"type\": \"categories\",\r\n            \"name\": \"Categories\",\r\n            \"totalResults\": 1,\r\n            \"results\": [\r\n                {\r\n                    \"link\": \"myshop.com/c/laptops\",\r\n                    \"name\": \"Laptops\"\r\n                }\r\n            ]\r\n        },\r\n    ],\r\n    \"totalResults\": 1,\r\n    \"interpretedQuery\": {\r\n        \"matchSources\": []\r\n    },\r\n    \"showAllResults\": true\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    searchResults:
                      - type: products
                        name: Products
                        totalResults: 136
                        totalResultsVariants: 136
                        results:
                          - - identifier: '10064765'
                              groupId: '10064765'
                              sxId: 77346208
                              sxCategoryId: ELECTRIC_GUITAR
                              dataPoints:
                                - id: 4714637
                                  key: Category
                                  type: PASS_ON
                                  value: Semi-Hollow & Jazz Guitars
                                  isCategory: true
                                - id: 4711258
                                  key: Brand Image
                                  type: PASS_ON
                                  value: 'https://media.justmusic.de/shop/images/hersteller/Gretsch.jpg'
                                - id: 4710490
                                  key: Brand
                                  type: PASS_ON
                                  value: Gretsch Guitars
                                - id: 4710618
                                  key: Availability
                                  type: PASS_ON
                                  value: immediately available - delivery time 1-3 workdays
                                - id: 4710493
                                  key: ArticleID
                                  type: PASS_ON
                                  value: '84333'
                                - id: 4710596
                                  key: Short Description
                                  type: PASS_ON
                                  value: Hollow-Body Electric Guitar
                                - id: 4711174
                                  key: Price
                                  type: PASS_ON
                                  value: €3949.00
                                  parsedValue: 3949
                              image: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/10064765_01.jpg
                              name: Gretsch Guitars G6136T-140 LTD 140th Double Platinum Falcon w./Bigsby 2-Tone /Stone Platinum
                              images:
                                - type: ALTERNATIVE
                                  url: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/10064765_01.jpg
                              link: //www.justmusic.de/en/Guitars-Basses/Electric-Guitars/Semi-Hollow-Jazz-Guitars/Gretsch-Guitars-G6136T-140-LTD-140th-Double-Platinum-Falcon-w-Bigsby-2-Tone-Stone-Platinum
                              resultSet: null
                              head: true
                              relevance: 1000000
                          - - identifier: '14006428'
                              groupId: '14006428'
                              sxId: 25035215
                              sxCategoryId: ELECTRIC_GUITAR
                              dataPoints:
                                - id: 4714637
                                  key: Category
                                  type: PASS_ON
                                  value: Semi-Hollow & Jazz Guitars
                                  isCategory: true
                                - id: 4711258
                                  key: Brand Image
                                  type: PASS_ON
                                  value: 'https://media.justmusic.de/shop/images/hersteller/Gretsch.jpg'
                                - id: 4710490
                                  key: Brand
                                  type: PASS_ON
                                  value: Gretsch Guitars
                                - id: 4710618
                                  key: Availability
                                  type: PASS_ON
                                  value: immediately available - delivery time 1-3 workdays
                                - id: 4710493
                                  key: ArticleID
                                  type: PASS_ON
                                  value: '65217'
                                - id: 4710596
                                  key: Short Description
                                  type: PASS_ON
                                  value: Hollow-Body Electric Guitar
                                - id: 4711174
                                  key: Price
                                  type: PASS_ON
                                  value: €3299.00
                                  parsedValue: 3299
                              image: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/14006428_01.jpg
                              name: Gretsch Guitars G6120TFM-BSNV Brian Setzer Sign. Nashville /w Bigsby Orange Stain
                              images:
                                - type: ALTERNATIVE
                                  url: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/14006428_01.jpg
                              link: //www.justmusic.de/en/Guitars-Basses/Electric-Guitars/Semi-Hollow-Jazz-Guitars/Gretsch-Guitars-G6120TFM-BSNV-Brian-Setzer-Sign-Nashville-w-Bigsby-Orange-Stain
                              resultSet: null
                              head: true
                              relevance: 999999
                          - - identifier: '10058143'
                              groupId: '10058143'
                              sxId: 25037296
                              sxCategoryId: ELECTRIC_GUITAR
                              dataPoints:
                                - id: 4714637
                                  key: Category
                                  type: PASS_ON
                                  value: Semi-Hollow & Jazz Guitars
                                  isCategory: true
                                - id: 4711258
                                  key: Brand Image
                                  type: PASS_ON
                                  value: 'https://media.justmusic.de/shop/images/hersteller/Gretsch.jpg'
                                - id: 4710490
                                  key: Brand
                                  type: PASS_ON
                                  value: Gretsch Guitars
                                - id: 4710618
                                  key: Availability
                                  type: PASS_ON
                                  value: immediately available - delivery time 1-3 workdays
                                - id: 4710493
                                  key: ArticleID
                                  type: PASS_ON
                                  value: '73433'
                                - id: 4710596
                                  key: Short Description
                                  type: PASS_ON
                                  value: Hollow-Body Electric Guitar
                                - id: 4711174
                                  key: Price
                                  type: PASS_ON
                                  value: €2499.00
                                  parsedValue: 2499
                              image: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/10058143_01.jpg
                              name: Gretsch Guitars G6118T-SGR Players Ed. Anniv.2-Tone Smoke Green
                              images:
                                - type: ALTERNATIVE
                                  url: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/10058143_01.jpg
                              link: //www.justmusic.de/en/Guitars-Basses/Electric-Guitars/Semi-Hollow-Jazz-Guitars/Gretsch-Guitars-G6118T-SGR-Players-Ed-Anniv-2-Tone-Smoke-Green
                              resultSet: null
                              head: true
                              relevance: 999998
                    totalResults: 136
                    interpretedQuery:
                      matchSources: []
                properties:
                  searchResults:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                        name:
                          type: string
                        totalResults:
                          type: integer
                        totalResultsVariants:
                          type: integer
                        results:
                          type: array
                          x-stoplight:
                            id: n6lhi0o0tiolv
                          items:
                            $ref: '#/components/schemas/SearchResult'
                  totalResults:
                    type: integer
                  interpretedQuery:
                    type: object
                    properties:
                      matchSources:
                        type: array
                        items:
                          type: object
        '404':
          description: "Not found\r\n\r\n```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 404,\r\n    \"message\": \"Sorry an error occurred. Please check the logs.\"\r\n}\r\n```"
      operationId: get-search-suggestions
      x-stoplight:
        id: l4138td8aakrx
      description: |-
        Call this endpoint to retrieve search suggestions as the user types. You can find more information about types of search suggestions in [this guide](https://docs.zoovu.com/api/guides/platform/search-suggestions).

        Please make sure to attach the session-id query parameter.

        Additionally, make sure to forward the client IP address via an HTTP header called HTTP_CLIENT_IP - this makes it possible to set a limit for queries per IP per hour to prevent abuse.
      parameters:
        - schema:
            type: integer
          in: query
          name: projectId
          description: your Data Platform project ID
          required: true
        - schema:
            type: string
          in: query
          name: query
          description: a search term
          required: true
        - schema:
            type: integer
          in: query
          name: limit
          description: how many results to return (ranging from 0 to 1000)
        - schema:
            type: string
          in: query
          name: userGroup
          description: 'if you defined user groups when importing your product data, you can use this parameter to set the appropriate user group for the user currently searching. This ensures the search results will respect all user-group-specific rules. Please see [this guide](https://docs.zoovu.com/api/guides/platform/user-groups) on user groups for more information.'
        - schema:
            type: string
          in: query
          name: sessionId
          description: a sessionId unique to the user
        - schema:
            type: string
          in: query
          name: includeContentGroups
          description: 'a URL-encoded JSON array that limits API response to these included result groups, e.g. `["Products"]`.'
        - schema:
            type: string
          in: query
          name: excludeContentGroups
          description: 'a URL-encoded JSON array that excludes these result groups from the API response, e.g. `["Blog"]`.'
        - schema:
            type: integer
          in: query
          name: catalogId
          description: you can limit search results to any of your Data Platform catalogs by providing the catalogId. You can copy the catalogId from the three-dot menu to the right of each catalog.
        - schema:
            type: string
          in: query
          name: filters
          description: |-
            A URL-encoded JSON array containing filters for product search OR content search (NOT both at the same time). Supports filtering by name, conceptIdName (recommended), or database ID, with options for collection, range, boolean, and content filters.

            Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting) for detailed syntax, examples, and additional filter options.
        - schema:
            type: string
          in: query
          name: preSetFilters
          description: |-
            A URL-encoded JSON array. Same schema as `filters`, but applied server-side and invisible to the end user. Used to pre-filter the product catalog for a specific integration (e.g., showing only available products or excluding certain categories).

            Please refer to [this guide](https://docs.zoovu.com/api/guides/platform/filters-sorting#pre-set-filters) for details and examples.
        - schema:
            type: string
          in: query
          name: sortComplex
          description: |-
            a URL-encoded JSON object containing the sorting information.

            You can sort using concept ID
            `{"key": "123421", "direction":"ASC"}`

            or concept identifier/conceptIdName:
            `{"conceptIdName": "PRICE", "direction":"ASC"}`

            Finally, you can also sort by ranking strategy ID, which you can copy from the three-dot menu next to your [ranking strategy](https://search.zoovu.com/ranking-strategies):
            `{"rankingStrategyId":"60fe8a94097548517a966752", "type":"STRATEGY"}`
        - schema:
            type: string
          in: query
          name: queryTag
          description: 'A free-form query tag, used to tag your queries so that they can later be clustered in search analytics. An example might be tagging traffic from your app (queryTag=app) and webstore (queryTag=store) differently.'
        - schema:
            type: boolean
          in: query
          name: caching
          description: define whether the results should be loaded from cache
        - schema:
            type: boolean
          in: query
          name: generateContentCounts
          description: 'if set, calculates available content result counts. Note: this may slow down the response.'
        - schema:
            type: string
          in: header
          name: HTTP_CLIENT_IP
          description: Please include the client IP in the HTTP_CLIENT_IP header to enable rate limiting and prevent API abuse.
  '/search/relations/result':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
      - schema:
          type: string
        name: identifier
        description: your internally used product ID
        in: query
        required: true
      - schema:
          type: string
          example: '[{"id":6548, "limit":5}]'
        name: includeRelations
        in: query
        description: |-
          Define which relations to resolve by sending a list of relation ids paired with a limit, e.g.,
          ```json
          [{"id":6548, "limit":5}, {"id":9878, "limit":5}]
          ```
      - schema:
          type: string
          example: '[{"tag":"Compatible", "limitPerRelation":4}]'
        name: includeTags
        in: query
        description: |-
          Define which relations to resolve by sending a list of tag objects paired with a limitPerRelation, e.g.,
          ```json
          [{"tag":"Compatible", "limitPerRelation":4}]
          ```
      - schema:
          type: string
        name: userGroup
        in: query
        description: restrict the related products by a user group
      - schema:
          type: string
        name: query
        in: query
        description: a search query to pre-filter which related products are eligible. Only products matching this search query will appear in the relation results.
      - schema:
          type: boolean
          default: false
        name: ignoreEmptyQueryResult
        in: query
        description: 'when `true` and the `query` parameter returns no search results, the query filter is ignored and all matching related products are returned. When `false` (default), an empty query result means no related products are returned.'
    get:
      summary: Get related products
      security: []
      tags:
        - Product Search
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n  \"tags\": [\r\n    {\r\n      \"tag\": \"Compatible\",\r\n      \"relations\": [\r\n        {\r\n          \"name\": \"Matching Accessories\",\r\n          \"id\": 4728,\r\n          \"searchResult\": [\r\n          {\r\n            \"identifier\": \"PRD-9876-BLU40\",\r\n            \"groupId\": \"9876\",\r\n            \"sxId\": 240538699,\r\n            \"name\": \"Laptop Case 9876 Blue\",\r\n            \"brand\": \"BrandX\",\r\n            \"category\": \"Cases\",\r\n            \"image\": \"www.myshop.com/product/9876-blu40/img.jpg\",\r\n            \"link\": \"www.myshop.com/product/9876-blu40\",\r\n            \"relevance\": 1000000\r\n          }\r\n          ]\r\n        }\r\n      ]\r\n    }\r\n  ]\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  tags:
                    type: array
                    items:
                      type: object
                      properties:
                        tag:
                          type: string
                        relations:
                          type: array
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                              id:
                                type: integer
                              localization:
                                type: object
                                properties:
                                  names:
                                    type: array
                                    items:
                                      type: object
                              searchResult:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    identifier:
                                      type: string
                                    groupId:
                                      type: string
                                    sxId:
                                      type: integer
                                    dataPoints:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: integer
                                          conceptIdName:
                                            type: string
                                          key:
                                            type: string
                                          type:
                                            type: string
                                          value:
                                            type: string
                                          isCategory:
                                            type: boolean
                                          show:
                                            type: boolean
                                          matched:
                                            type: boolean
                                    image:
                                      type: string
                                    name:
                                      type: string
                                    images:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          type:
                                            type: string
                                          url:
                                            type: string
                                    link:
                                      type: string
                                    head:
                                      type: boolean
                                    relevance:
                                      type: integer
                x-examples:
                  Example 1:
                    tags:
                      - tag: Compatible
                        relations:
                          - name: Matching Accessories
                            id: 4728
                            localization:
                              names: []
                            searchResult:
                              - - identifier: PRD-9876-BLU40
                                  groupId: '9876'
                                  sxId: 240538699
                                  dataPoints:
                                    - id: 281559600
                                      conceptIdName: CATEGORY
                                      key: Category
                                      type: PASS_ON
                                      value: Cases
                                      isCategory: true
                                    - id: 288188589
                                      conceptIdName: BRAND
                                      key: Brand
                                      value: BrandX
                                      show: true
                                      matched: true
                                      type: FILTER
                                  image: www.myshop.com/product/9876-blu40/img.jpg
                                  name: Laptop Case 9876 Blue
                                  images:
                                    - type: ALTERNATIVE
                                      url: www.myshop.com/product/9876-blu40/img.jpg
                                  link: www.myshop.com/product/9876-blu40
                                  head: false
                                  relevance: 1000000
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: failure
                code: 404
                message: Your requested product was not found
      operationId: get-resolved-relations
      x-stoplight:
        id: p5ge7fr8w0aao
      description: "Returns related products for a single product based on identifier. \r\n\r\n⚠️ **At least one of `includeRelations` or `includeTags` must be provided. Omitting both returns a `400 Bad Request` error.** You may send both.\r\n\r\n**includeRelations:** define which relations to resolve by sending a list of relation ids paired with a limit.\r\n\r\nExample: `[{\"id\":6548, \"limit\":5}, {\"id\":9878, \"limit\":5}]` \r\n\r\nRelation ids can be copied from the three-dot menu next to each relation in the Data Platform. The limit determines how many related products are returned per requested relation.\r\n\r\n**includeTags:** define which relations to resolve by sending a list of tag objects paired with a limitPerRelation.\r\n\r\nExample: `[{\"tag\":\"Compatible\", \"limitPerRelation\":4}]` \r\n\r\nTags correspond with the relation type found in the Data Platform. limitPerRelation specifies how many products can be returned for each relation with a matching tag."
  '/search/relations/bulk-results':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
      - schema:
          type: string
        name: identifiers
        description: |-
          a URL-encoded JSON array of product identifiers, e.g.,
          ```json
          ["WTU87675NL","WAU28R70NL"]
          ```
        in: query
        required: true
      - schema:
          type: string
          example: '[{"id": 234232, "limit":2}]'
        name: includeRelations
        in: query
        description: |-
          a URL-encoded JSON array of relation objects, e.g.,
          ```json
          [{"id": 234232, "limit":2}]
          ```
      - schema:
          type: string
          example: '[{"tag":"Compatible", "limitPerRelation":4}]'
        name: includeTags
        in: query
        description: |-
          a URL-encoded JSON array of tag objects, e.g.,
          ```json
          [{"tag":"Compatible", "limitPerRelation":4}]
          ```
      - schema:
          type: string
        name: userGroup
        in: query
        description: restrict the related products by a user group
    get:
      summary: Get related products (bulk)
      security: []
      tags:
        - Product Search
      operationId: get-relations-bulk
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"424357\": {\r\n        \"tags\": [\r\n            {\r\n                \"tag\": \"Compatible\",\r\n                \"relations\": [\r\n                    {\r\n                        \"name\": \"Matching Accessories\",\r\n                        \"id\": 4728,\r\n                        \"localization\": {\r\n                            \"names\": []\r\n                        },\r\n                        \"searchResult\": [\r\n                            [\r\n                                {\r\n                                    \"identifier\": \"PRD-9876-BLU40\",\r\n                                    \"groupId\": \"9876\",\r\n                                    \"sxId\": 240538699,\r\n                                    \"dataPoints\": [\r\n                                        {\r\n                                            \"id\": 281559600,\r\n                                            \"conceptIdName\": \"CATEGORY\",\r\n                                            \"key\": \"Category\",\r\n                                            \"type\": \"PASS_ON\",\r\n                                            \"value\": \"Cases\",\r\n                                            \"isCategory\": true\r\n                                        }\r\n                                    ],\r\n                                    \"image\": \"www.myshop.com/product/9876-blu40/img.jpg\",\r\n                                    \"name\": \"Laptop Case 9876 Blue\",\r\n                                    \"images\": [\r\n                                        {\r\n                                            \"type\": \"ALTERNATIVE\",\r\n                                            \"url\": \"www.myshop.com/product/9876-blu40/img.jpg\"\r\n                                        }\r\n                                    ],\r\n                                    \"link\": \"www.myshop.com/product/9876-blu40\",\r\n                                    \"head\": false,\r\n                                    \"relevance\": 1000000\r\n                                }\r\n                            ]\r\n                        ]\r\n                    }\r\n                ]\r\n            }\r\n        ]\r\n    },\r\n    \"484365\": {\r\n        \"tags\": [\r\n            {\r\n                \"tag\": \"Compatible\",\r\n                \"relations\": [\r\n                    {\r\n                        \"name\": \"Matching Accessories\",\r\n                        \"id\": 4728,\r\n                        \"localization\": {\r\n                            \"names\": []\r\n                        },\r\n                        \"searchResult\": [\r\n                            [\r\n                                {\r\n                                    \"identifier\": \"PRD-5432-SLV20\",\r\n                                    \"groupId\": \"5432\",\r\n                                    \"sxId\": 240538701,\r\n                                    \"dataPoints\": [\r\n                                        {\r\n                                            \"id\": 281559600,\r\n                                            \"conceptIdName\": \"CATEGORY\",\r\n                                            \"key\": \"Category\",\r\n                                            \"type\": \"PASS_ON\",\r\n                                            \"value\": \"Cases\",\r\n                                            \"isCategory\": true\r\n                                        }\r\n                                    ],\r\n                                    \"image\": \"www.myshop.com/product/5432-slv20/img.jpg\",\r\n                                    \"name\": \"Laptop Case 5432 Silver\",\r\n                                    \"images\": [\r\n                                        {\r\n                                            \"type\": \"ALTERNATIVE\",\r\n                                            \"url\": \"www.myshop.com/product/5432-slv20/img.jpg\"\r\n                                        }\r\n                                    ],\r\n                                    \"link\": \"www.myshop.com/product/5432-slv20\",\r\n                                    \"head\": false,\r\n                                    \"relevance\": 999999\r\n                                }\r\n                            ]\r\n                        ]\r\n                    }\r\n                ]\r\n            }\r\n        ]\r\n    }\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                description: 'an object keyed by product identifier, where each value contains the relation results for that product'
                additionalProperties:
                  type: object
                  properties:
                    tags:
                      type: array
                      items:
                        type: object
                        properties:
                          tag:
                            type: string
                          relations:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                id:
                                  type: integer
                                localization:
                                  type: object
                                  properties:
                                    names:
                                      type: array
                                      items:
                                        type: object
                                searchResult:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      identifier:
                                        type: string
                                      groupId:
                                        type: string
                                      sxId:
                                        type: integer
                                      dataPoints:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            id:
                                              type: integer
                                            conceptIdName:
                                              type: string
                                            key:
                                              type: string
                                            type:
                                              type: string
                                            value:
                                              type: string
                                            isCategory:
                                              type: boolean
                                            show:
                                              type: boolean
                                            matched:
                                              type: boolean
                                      image:
                                        type: string
                                      name:
                                        type: string
                                      images:
                                        type: array
                                        items:
                                          type: object
                                          properties:
                                            type:
                                              type: string
                                            url:
                                              type: string
                                      link:
                                        type: string
                                      head:
                                        type: boolean
                                      relevance:
                                        type: integer
              x-examples:
                Example 1:
                  '424357':
                    tags:
                      - tag: Compatible
                        relations:
                          - name: Matching Accessories
                            id: 4728
                            localization:
                              names: []
                            searchResult:
                              - - identifier: PRD-9876-BLU40
                                  groupId: '9876'
                                  sxId: 240538699
                                  dataPoints:
                                    - id: 281559600
                                      conceptIdName: CATEGORY
                                      key: Category
                                      type: PASS_ON
                                      value: Cases
                                      isCategory: true
                                  image: www.myshop.com/product/9876-blu40/img.jpg
                                  name: Laptop Case 9876 Blue
                                  images:
                                    - type: ALTERNATIVE
                                      url: www.myshop.com/product/9876-blu40/img.jpg
                                  link: www.myshop.com/product/9876-blu40
                                  head: false
                                  relevance: 1000000
                  '484365':
                    tags:
                      - tag: Compatible
                        relations:
                          - name: Matching Accessories
                            id: 4728
                            localization:
                              names: []
                            searchResult:
                              - - identifier: PRD-5432-SLV20
                                  groupId: '5432'
                                  sxId: 240538701
                                  dataPoints:
                                    - id: 281559600
                                      conceptIdName: CATEGORY
                                      key: Category
                                      type: PASS_ON
                                      value: Cases
                                      isCategory: true
                                  image: www.myshop.com/product/5432-slv20/img.jpg
                                  name: Laptop Case 5432 Silver
                                  images:
                                    - type: ALTERNATIVE
                                      url: www.myshop.com/product/5432-slv20/img.jpg
                                  link: www.myshop.com/product/5432-slv20
                                  head: false
                                  relevance: 999999
        '400':
          description: Bad Request
        '404':
          description: Not Found
      description: |-
        Retrieve relation results for multiple product identifiers at once.

        ⚠️ **At least one of `includeRelations` or `includeTags` must be provided. Omitting both returns a `400 Bad Request` error.** You may send both.
  '/comparison/compare':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        in: query
        required: true
      - schema:
          type: string
        name: sessionId
        in: query
        description: a session ID unique to the user
      - schema:
          type: string
        name: userGroup
        in: query
        description: restrict the compared products by a user group
      - schema:
          type: string
          enum:
            - PIM
            - MINI_PDP
            - REFINEMENT
            - ZOE
            - PASS_ON
            - PASS_ON_SUGGESTION
            - ASSISTANT
            - MCP
            - RELATIONS
        name: maskType
        in: query
        description: 'Filters the comparison attributes by mask type. Only attributes included in a mask of the specified type will appear in the comparison groups. Case-insensitive.'
    post:
      summary: Compare products
      tags:
        - Product Search
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"products\": [\r\n        {\r\n            \"id\": 258985256,\r\n            \"title\": \"Headphones R\",\r\n            \"identifier\": \"1122336\",\r\n            \"groupIdentifier\": \"1122336\",\r\n            \"image\": \"www.myshop.com/product/1122336/img.jpg\",\r\n            \"url\": \"www.myshop.com/product/1122336\",\r\n            \"images\": [\r\n                {\r\n                    \"url\": \"www.myshop.com/product/1122336/img.jpg\",\r\n                    \"type\": \"SMALL\"\r\n                }\r\n            ],\r\n            \"newPrice\": \"99.99\",\r\n            \"newPriceUnit\": \"$\",\r\n            \"comparison\": {\r\n                \"Product Details\": {\r\n                    \"color\": [\r\n                        \"blue\"\r\n                    ],\r\n                    \"Manufacturer\": [\r\n                        \"BrandZ\"\r\n                    ],\r\n                    \"price\": [\r\n                        \"99.99 $\"\r\n                    ]\r\n                }\r\n            }\r\n        },\r\n        {\r\n            \"id\": 258985244,\r\n            \"title\": \"Headphones O\",\r\n            \"identifier\": \"4455668\",\r\n            \"groupIdentifier\": \"4455668\",\r\n            \"image\": \"www.myshop.com/product/4455668/img.jpg\",\r\n            \"url\": \"www.myshop.com/product/4455668\",\r\n            \"images\": [\r\n                {\r\n                    \"url\": \"www.myshop.com/product/4455668/img.jpg\",\r\n                    \"type\": \"SMALL\"\r\n                }\r\n            ],\r\n            \"newPrice\": \"149.99\",\r\n            \"newPriceUnit\": \"$\",\r\n            \"comparison\": {\r\n                \"Product Details\": {\r\n                    \"color\": [\r\n                        \"black\"\r\n                    ],\r\n                    \"Manufacturer\": [\r\n                        \"BrandX\"\r\n                    ],\r\n                    \"price\": [\r\n                        \"149.99 $\"\r\n                    ]\r\n                }\r\n            }\r\n        }\r\n    ],\r\n    \"icons\": {},\r\n    \"booleans\": {},\r\n    \"explainerAttributes\": [],\r\n    \"viewId\": \"60548\"\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                x-examples:
                  Example 1:
                    products:
                      - id: 258985256
                        title: Headphones R
                        identifier: '1122336'
                        groupIdentifier: '1122336'
                        image: www.myshop.com/product/1122336/img.jpg
                        url: www.myshop.com/product/1122336
                        images:
                          - url: www.myshop.com/product/1122336/img.jpg
                            type: SMALL
                        newPrice: '99.99'
                        newPriceUnit: $
                        comparison:
                          Product Details:
                            color:
                              - blue
                            Manufacturer:
                              - BrandZ
                            price:
                              - 99.99 $
                      - id: 258985244
                        title: Headphones O
                        identifier: '4455668'
                        groupIdentifier: '4455668'
                        image: www.myshop.com/product/4455668/img.jpg
                        url: www.myshop.com/product/4455668
                        images:
                          - url: www.myshop.com/product/4455668/img.jpg
                            type: SMALL
                        newPrice: '149.99'
                        newPriceUnit: $
                        comparison:
                          Product Details:
                            color:
                              - black
                            Manufacturer:
                              - BrandX
                            price:
                              - 149.99 $
                    icons: {}
                    booleans: {}
                    explainerAttributes: []
                    viewId: '60548'
                properties:
                  products:
                    type: array
                    description: 'the comparison result, an array of JSON objects'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        title:
                          type: string
                        identifier:
                          type: string
                        groupIdentifier:
                          type: string
                        image:
                          type: string
                        url:
                          type: string
                        images:
                          type: array
                          items:
                            type: object
                            properties:
                              url:
                                type: string
                              type:
                                type: string
                        newPrice:
                          type: string
                          description: 'the current price value as a string, if a price attribute with the newPrice setting exists'
                        newPriceUnit:
                          type: string
                          description: 'the unit for the current price (e.g. $, €)'
                        comparison:
                          type: object
                          description: 'A JSON object keyed by comparison group name. Each group contains attributes as keys, with values as string arrays. Empty arrays indicate no value for that attribute.'
                          additionalProperties:
                            type: object
                            additionalProperties:
                              type: array
                              items:
                                type: string
                  icons:
                    type: object
                    description: Icon mappings for comparison attributes (if configured)
                  booleans:
                    type: object
                    description: Boolean attribute mappings for comparison attributes (if configured)
                  explainerAttributes:
                    type: array
                    description: An array of attribute IDs that should be displayed with an explanation text in the frontend
                    items:
                      type: object
                  viewId:
                    type: string
                    description: a unique event ID (string for event tracking)
        '400':
          description: "Bad Request\r\n\r\n`{\r\n    \"status\": \"failure\",\r\n    \"code\": 400,\r\n    \"message\": \"Products must be given\"\r\n}`"
      operationId: compare-products
      x-stoplight:
        id: 34c1iafdx0eja
      requestBody:
        description: "`{\r\n  \"products\": [\r\n    \"identifier1\",\r\n    \"identifier2\",\r\n    \"identifier3\"\r\n  ]\r\n}`"
        content:
          application/json:
            schema:
              type: object
              properties:
                products:
                  type: array
                  items:
                    type: string
              x-examples:
                Example 1:
                  products:
                    - '4455668'
                    - '1122336'
            examples:
              Example 1:
                value:
                  products:
                    - '4455668'
                    - '1122336'
      description: 'Send the identifiers of the products you wish to compare to this endpoint to retrieve your configured [comparison groups and associated attributes](https://data.zoovu.com/comparison) from Data Platform.'
  '/platform/v1/{project-id}/concepts':
    parameters:
      - schema:
          type: string
        name: project-id
        description: 'your Data Platform project ID. If you have a multilocale setup, you can provide any project ID in your folder - the ontology is shared with all projects automatically.'
        in: path
        required: true
    put:
      summary: Create or update concepts
      tags:
        - Ontology Management
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessConceptUpdateResponse'
        '400':
          description: "Invalid concept schema\r\nInvalid parameter values"
      operationId: create-or-update-concepts
      x-stoplight:
        id: 5bxj49r3fq5nl
      description: "Creates new concepts (i.e., categories, attributes, and text values) \r\nor updates existing ones. \r\n\r\nThe request body consists of **concepts and their related data** and **update options**. \r\n\r\nThe update option `syncMode` determines how existing concepts are affected by the new request.\r\nIf set to `FULL`, all concepts that are currently present in the Data Platform, but are \r\nnot part of the latest request, will be deleted. In this case, it is important that the latest request **represents the full ontology**.\r\n\r\nIf you do not want to remove any concepts, you can set the `syncMode` parameter to `INCREMENTAL`. With this mode, new concepts can be created and existing concepts can be enriched with additional extraction rules or synonyms. **No concepts will be removed**.\r\n\r\nThe `writeMode` parameter allows you to determine whether the request should `OVERWRITE` existing concept data or `MERGE` the latest concept data with the existing concept data. \r\n\r\n`ignoreModified` determines whether concepts that were adjusted manually in the Data Platform should be affected by the update. If set to true, concepts that have been modified by a user will be \"ignored\" during the ontology update, **ensuring manual changes are preserved** when automated sync processes run.\r\nIn other words, if a concept was tweaked by a human in the UI, setting `ignoreModified` to true tells the system: \"don’t touch it.\" \r\n\r\n**Note for multilocale setups:** If your concepts have translations in multiple languages, you can define a language-dependent `name` as well as language-dependent `synonyms` and `extractionRules`.\r\nExtraction rules define which input data should be matched in order for a concept to be extracted and a corresponding fact created (see documentation: \r\nhttps://docs.zoovu.com/data-platform/ontology/extraction-rules).\r\n\r\nIf no extraction rules are sent, Data Platform automatically derives a `MATCH` extraction rule from the name. \r\nYou can see the automatically-generated extraction rules in the response. The response reflects the concepts as they \r\nare stored in the Data Platform."
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              type: object
              example:
                updateOptions:
                  syncMode: INCREMENTAL
                  updateConstraints:
                    writeMode: MERGE
                    ignoreModified: false
                concepts:
                  - idName: BACKPACKS
                    type: CATEGORY
                    description: All types of backpacks for hiking, travel, and everyday use.
                    structuredViewData:
                      url:
                        link: 'https://example.com/aLinkToACategoryPage'
                        sourceType: AUTOMATIC
                      passOnImage:
                        link: 'https://example.com/image2.png'
                        sourceType: AUTOMATIC
                      filterImage:
                        link: 'https://example.com/image3.png'
                        sourceType: AUTOMATIC
                    localization:
                      de:
                        name: Rucksäcke
                      en:
                        name: backpacks
                        synonyms:
                          - rucksacks
                        extractionRules:
                          - type: IS
                            text:
                              - type: MATCH
                                text: Hiking packs
                    children:
                      - idName: BACKPACKS/TREKKING
                        type: CATEGORY
                        description: Backpacks designed for multi-day trekking and hiking trips.
                        localization:
                          de:
                            name: Trekking
                          en:
                            name: trekking
                        children:
                          - idName: BACKPACKS/TREKKING/WOMENS_TREKKING
                            type: CATEGORY
                            localization:
                              de:
                                name: Damen Trekking
                              en:
                                name: women's trekking
                                extractionRules:
                                  - type: IS
                                    text:
                                      - type: CONTAINS
                                        text: Women
                                      - type: CONTAINS
                                        text: trek
                      - idName: BACKPACKS/NOTEBOOK
                        type: CATEGORY
                        localization:
                          de:
                            name: Rucksäcke für Notebooks
                          en:
                            name: notebook backpacks
                  - idName: ACCESSORIES
                    type: CATEGORY
                    localization:
                      de:
                        name: Zubehör
                      en:
                        name: accessories
                  - idName: PRICE
                    type: NUMERIC_ATTRIBUTE
                    localization:
                      de:
                        name: Preis
                        unitName: €
                        synonyms:
                          - Verkaufspreis
                        extractionRules:
                          - type: IS
                            text:
                              - type: MATCH
                                text: Preis
                      en:
                        name: price
                      en-US:
                        unitName: $
                      en-CA:
                        unitName: $
                      en-GB:
                        unitName: £
                  - idName: COLOR
                    type: TEXT_ATTRIBUTE
                    description: This is the color attribute we use for filtering
                    localization:
                      de:
                        name: Farbe
                      en:
                        name: color
                    children:
                      - idName: RED
                        type: TEXT_VALUE
                        localization:
                          de:
                            name: Rot
                          en:
                            name: red
                            synonyms:
                              - cherry
                            extractionRules:
                              - type: IS
                                text:
                                  - type: MATCH
                                    text: wine
                  - idName: AVAILABILITY
                    type: BOOLEAN_ATTRIBUTE
                    localization:
                      de:
                        name: Verfügbarkeit
                        trueState: ist verfügbar
                        falseState: nicht verfügbar
                        extractionRules:
                          - type: IS
                            text:
                              - type: MATCH
                                text: availability
                              - type: MATCH
                                text: ist verfügbar
                            boolValue: 'TRUE'
                          - type: IS
                            text:
                              - type: MATCH
                                text: availability
                              - type: MATCH
                                text: nicht verfügbar
                            boolValue: 'FALSE'
                      en:
                        name: availability
                        trueState: in stock
                        falseState: out of stock
                        extractionRules:
                          - type: IS
                            text:
                              - type: MATCH
                                text: availability
                              - type: MATCH
                                text: in stock
                            boolValue: 'TRUE'
                          - type: IS
                            text:
                              - type: MATCH
                                text: availability
                              - type: MATCH
                                text: out of stock
                            boolValue: 'FALSE'
                  - idName: DESCRIPTION
                    type: UNTYPED_ATTRIBUTE
                    localization:
                      de:
                        name: Beschreibung
                      en:
                        name: description
                    keyValuePairs:
                      someKey: some value
              required:
                - concepts
              properties:
                updateOptions:
                  type: object
                  x-stoplight:
                    id: dhq0u35xhc877
                  required:
                    - syncMode
                    - updateConstraints
                  properties:
                    syncMode:
                      x-stoplight:
                        id: b8ohhycwzf3jk
                      enum:
                        - FULL
                        - INCREMENTAL
                      description: "The `syncMode` determines how existing concepts are affected by this update.\r\n\r\n`FULL`: the current ontology will be replaced with the one contained in the request - any previously existing concept not included in the request will be deleted. Make sure you are sending your complete ontology.\r\n\r\n`INCREMENTAL`: all new concepts included in the request are added to the existing ontology and already-existing concepts are updated. No concepts are deleted."
                      default: INCREMENTAL
                    updateConstraints:
                      type: object
                      x-stoplight:
                        id: vlm0f50reojuu
                      properties:
                        writeMode:
                          x-stoplight:
                            id: dj361stghzugr
                          enum:
                            - MERGE
                            - OVERWRITE
                          description: "The `writeMode` determines how existing concepts are updated. \r\n\r\n`OVERWRITE`: existing concepts are replaced with the concepts in the request\r\n\r\n`MERGE`: the concept data in the request is merged with existing concept data. \r\n\r\n`MERGE` affects the different fields of a concept in the following ways: All single-value fields like type, url.value, passOnImage.value, localization.[language].name, etc. are replaced. All array fields (e.g., extractionRules and synonyms) and maps (e.g., attribute-value pairs) are enriched and existing values are NOT removed."
                          default: MERGE
                        ignoreModified:
                          type: boolean
                          x-stoplight:
                            id: a9pobghpij241
                          description: '`ignoreModified` determines whether concepts that were adjusted manually in the Data Platform should be affected by the update. If set to true, concepts that have been modified by a user in the UI will be "ignored" during the ontology update, **ensuring manual changes are preserved**.'
                          default: true
                concepts:
                  type: array
                  x-stoplight:
                    id: epcfy3qrcq3xw
                  items:
                    $ref: '#/components/schemas/Concept'
      security:
        - apiKeyHeader: []
    get:
      summary: Get concepts
      tags:
        - Ontology Management
      responses:
        '200':
          description: "```json\r\n{\r\n  \"concepts\": [\r\n    {\r\n      \"idName\": \"ROOT/Gift\",\r\n      \"type\": \"CATEGORY\",\r\n      \"localization\": {\r\n        \"en\": {\r\n          \"name\": \"Gift\",\r\n          \"synonyms\": [\r\n            \"gifts\"\r\n          ],\r\n          \"extractionRules\": [\r\n            {\r\n              \"type\": \"IS\",\r\n              \"text\": [\r\n                {\r\n                  \"type\": \"MATCH\",\r\n                  \"text\": \"root gift\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"children\": [\r\n        {\r\n          \"idName\": \"ROOT/Gift/Gifts up to 200 euros\",\r\n          \"type\": \"CATEGORY\",\r\n          \"localization\": {\r\n            \"en\": {\r\n              \"name\": \"Gifts up to 200 euros\",\r\n              \"extractionRules\": [\r\n                {\r\n                  \"type\": \"IS\",\r\n                  \"text\": [\r\n                    {\r\n                      \"type\": \"MATCH\",\r\n                      \"text\": \"root gift gifts up to 200 euros\"\r\n                    }\r\n                  ]\r\n                }\r\n              ]\r\n            }\r\n          },\r\n          \"children\": [\r\n            {\r\n              \"idName\": \"ROOT/Gift/Gifts up to 200 euros/Games\",\r\n              \"type\": \"CATEGORY\",\r\n              \"localization\": {\r\n                \"en\": {\r\n                  \"name\": \"Games\",\r\n                  \"synonyms\": [\r\n                    \"game\"\r\n                  ],\r\n                  \"extractionRules\": [\r\n                    {\r\n                      \"type\": \"IS\",\r\n                      \"text\": [\r\n                        {\r\n                          \"type\": \"MATCH\",\r\n                          \"text\": \"root gift gifts up to 200 euros games\"\r\n                        }\r\n                      ]\r\n                    }\r\n                  ]\r\n                }\r\n              },\r\n              \"structuredViewData\": {\r\n                \"url\": {\r\n                  \"link\": \"\"\r\n                }\r\n              }\r\n            }\r\n          ]\r\n        }\r\n      ]\r\n    },\r\n    {\r\n      \"idName\": \"Bestseller\",\r\n      \"type\": \"BOOLEAN_ATTRIBUTE\",\r\n      \"localization\": {\r\n        \"en\": {\r\n          \"name\": \"Bestseller\",\r\n          \"trueState\": \"yes\",\r\n          \"falseState\": \"no\",\r\n          \"extractionRules\": [\r\n            {\r\n              \"type\": \"IS\",\r\n              \"text\": [\r\n                {\r\n                  \"type\": \"MATCH\",\r\n                  \"text\": \"bestseller\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"structuredViewData\": {}\r\n    },\r\n    {\r\n      \"idName\": \"BRAND\",\r\n      \"type\": \"TEXT_ATTRIBUTE\",\r\n      \"localization\": {\r\n        \"en\": {\r\n          \"name\": \"Brand\",\r\n          \"extractionRules\": [\r\n            {\r\n              \"type\": \"IS\",\r\n              \"text\": [\r\n                {\r\n                  \"type\": \"MATCH\",\r\n                  \"text\": \"brand\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"children\": [\r\n        {\r\n          \"idName\": \"BRAND_#_BRANDA\",\r\n          \"type\": \"TEXT_VALUE\",\r\n          \"localization\": {\r\n            \"en\": {\r\n              \"name\": \"BrandA\",\r\n              \"extractionRules\": [\r\n                {\r\n                  \"type\": \"IS\",\r\n                  \"text\": [\r\n                    {\r\n                      \"type\": \"MATCH\",\r\n                      \"text\": \"branda\"\r\n                    }\r\n                  ]\r\n                }\r\n              ]\r\n            }\r\n          },\r\n          \"structuredViewData\": {}\r\n        },\r\n        {\r\n          \"idName\": \"BRAND_#_BRANDB\",\r\n          \"type\": \"TEXT_VALUE\",\r\n          \"localization\": {\r\n            \"en\": {\r\n              \"name\": \"BrandB\",\r\n              \"extractionRules\": [\r\n                {\r\n                  \"type\": \"IS\",\r\n                  \"text\": [\r\n                    {\r\n                      \"type\": \"MATCH\",\r\n                      \"text\": \"brandb\"\r\n                    }\r\n                  ]\r\n                }\r\n              ]\r\n            }\r\n          },\r\n          \"structuredViewData\": {}\r\n        }\r\n      ]\r\n    },\r\n    {\r\n      \"idName\": \"DESCRIPTION\",\r\n      \"type\": \"UNTYPED_ATTRIBUTE\",\r\n      \"localization\": {\r\n        \"en\": {\r\n          \"name\": \"Description\",\r\n          \"extractionRules\": [\r\n            {\r\n              \"type\": \"IS\",\r\n              \"text\": [\r\n                {\r\n                  \"type\": \"MATCH\",\r\n                  \"text\": \"description\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"structuredViewData\": {}\r\n    },\r\n    {\r\n      \"idName\": \"PRICE\",\r\n      \"type\": \"NUMERIC_ATTRIBUTE\",\r\n      \"localization\": {\r\n        \"en\": {\r\n          \"name\": \"Price\",\r\n          \"unitName\": \"USD\",\r\n          \"extractionRules\": [\r\n            {\r\n              \"type\": \"IS\",\r\n              \"text\": [\r\n                {\r\n                  \"type\": \"MATCH\",\r\n                  \"text\": \"price\"\r\n                }\r\n              ]\r\n            }\r\n          ]\r\n        }\r\n      },\r\n      \"structuredViewData\": {}\r\n    }\r\n  ]\r\n}\r\n```"
          headers:
            'content-type:application-json':
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  concepts:
                    type: array
                    x-stoplight:
                      id: 6l4n758zbzvzt
                    items:
                      $ref: '#/components/schemas/Concept'
        '400':
          description: "```json\r\n{\r\n    \"status\": \"failure\",\r\n    \"code\": 400,\r\n    \"message\": \"Invalid query parameter. A json array is expected.\"\r\n}\r\n```"
      operationId: get-concepts
      x-stoplight:
        id: 9fp6roawftmw7
      description: "This endpoint retrieves all concepts in your ontology (i.e., categories, attributes, and text values).\r\n\r\nWhen requesting concepts, you can filter by `id-names` and/or the following `concept types`: \r\n- CATEGORY\r\n- NUMERIC_ATTRIBUTE \r\n- TEXT_ATTRIBUTE\r\n- BOOLEAN_ATTRIBUTE\r\n- UNTYPED_ATTRIBUTE\r\n- DATE_ATTRIBUTE\r\n\r\n\r\n\r\n    "
      security:
        - apiKeyHeader: []
      parameters:
        - schema:
            type: string
          in: query
          name: id-names
          description: An array of idNames the received concepts should be filtered by
        - schema:
            type: string
          in: query
          name: types
          description: An array of concept types the received concepts should be filtered by
    delete:
      summary: Delete concepts
      tags:
        - Ontology Management
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
              example:
                status: success
                message: Concepts deleted
      operationId: delete-concepts
      x-stoplight:
        id: q8kyf684jnlrw
      description: 'Deletes concepts from your ontology. If no parameters are defined, the full ontology will be deleted.'
      parameters:
        - schema:
            type: string
          in: query
          name: idNames
          description: A list of idNames. The corresponding concepts will be deleted.
        - schema:
            type: string
          in: query
          name: types
          description: A list of concept types. All concepts with these types will be deleted.
      security:
        - apiKeyHeader: []
  '/tasks/{taskId}':
    parameters:
      - schema:
          type: string
        name: taskId
        description: the task ID to check
        in: path
        required: true
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    get:
      summary: Get task information
      tags:
        - Tasks
      operationId: get-task-information
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"projectId\": 39074,\r\n    \"projectName\": null,\r\n    \"origin\": \"LIVE-API\",\r\n    \"taskStatus\": \"FINISHED\",\r\n    \"name\": \"Api triggered full update\",\r\n    \"taskIncrementType\": \"STEP_BASED\",\r\n    \"failure\": false,\r\n    \"requestTime\": 1744638748765,\r\n    \"startTime\": 1744638748766,\r\n    \"finishTime\": 1744638780000,\r\n    \"progress\": 1,\r\n    \"logCounter\": 5,\r\n    \"id\": \"67fd131c34ff64223a195b14\"\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  projectId:
                    type: integer
                  projectName:
                    nullable: true
                  origin:
                    type: string
                    example: LIVE-API
                  taskStatus:
                    type: string
                    example: FINISHED
                    description: 'Task status, e.g. PENDING, RUNNING, FINISHED'
                  name:
                    type: string
                  taskIncrementType:
                    type: string
                    example: STEP_BASED
                  failure:
                    type: boolean
                  requestTime:
                    type: integer
                  startTime:
                    type: integer
                    nullable: true
                  finishTime:
                    type: integer
                    nullable: true
                  progress:
                    type: number
                    description: 'Progress from 0 to 1. A value of 1 means the task is finished.'
                  logCounter:
                    type: integer
                  id:
                    type: string
        '404':
          description: Not Found
      description: |-
        Check the status and progress of an asynchronous task. The `progress` field ranges from 0 to 1, where 1 means the task is finished.

        Task IDs are returned by product upload, update, and other asynchronous operations.
  '/task-monitoring/update':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    get:
      summary: Get last updates information
      tags:
        - Tasks
      operationId: get-last-updates-information
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
                    properties:
                      hasScheduledUpdates:
                        type: boolean
                      scheduledUpdates:
                        type: array
                        items:
                          type: string
                      lastGenUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastFullUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastScheduledUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastIncrementalUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastPartialIncrementalUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastManualUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
                      lastManualSingleUpdateTask:
                        $ref: '#/components/schemas/TaskInfo'
              example:
                status: success
                data:
                  hasScheduledUpdates: false
                  scheduledUpdates: []
                  lastGenUpdateTask:
                    _id:
                      $oid: 62b9328a786ed77cebfbd5c6
                    projectId: 123456
                    projectName: null
                    origin: LIVE-API
                    taskStatus: FINISHED
                    taskKind: GENERAL_UPDATE
                    taskKindReadable: General Update
                    failure: false
                    message: ''
                    requestTime: 1656304266644
                    requestTimeString: '2022-06-27 06:31:06'
                    startTime: 1656304266657
                    startTimeString: '2022-06-27 06:31:06'
                    finishTime: 1656304311447
                    finishTimeString: '2022-06-27 06:31:51'
                    nrOfItems: 2808
                    nrOfProcessedItems: 2808
                    progress: 1
                    logCounter: 0
                  lastFullUpdateTask:
                    _id:
                      $oid: 62b93282786ed77cebfbd506
                    projectId: 123456
                    projectName: null
                    origin: LIVE-API
                    taskStatus: FINISHED
                    taskKind: FULL_UPDATE
                    taskKindReadable: Full Update
                    failure: false
                    message: ''
                    requestTime: 1656304258425
                    requestTimeString: '2022-06-27 06:30:58'
                    startTime: 1656304258433
                    startTimeString: '2022-06-27 06:30:58'
                    finishTime: 1656304319847
                    finishTimeString: '2022-06-27 06:31:59'
                    nrOfItems: 3
                    nrOfProcessedItems: 3
                    progress: 1
                    logCounter: 0
                  lastScheduledUpdateTask: null
                  lastIncrementalUpdateTask: null
                  lastPartialIncrementalUpdateTask: null
                  lastManualUpdateTask: null
                  lastManualSingleUpdateTask: null
        '404':
          description: Not Found
      description: Receive information about the last updates run for this project. This can be used to monitor whether updates are completing successfully.
  '/filters':
    servers:
      - url: 'https://api.search.zoovu.com'
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    put:
      summary: Set filters
      tags:
        - Filters
      operationId: set-filters
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: "OK\r\n\r\n```json\r\n{\r\n    \"status\": \"success\",\r\n    \"message\": \"Filters added\"\r\n}\r\n```"
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  message:
                    type: string
                    example: Filters added
      description: |-
        Store the filters of a project. The filters are based on the detected concepts.

        Each filter object specifies a `conceptId` and `settings` that control the filter type, sort order, visibility threshold, and position.

        For COLLECTION type filters, you can also specify `excludedTextValueIds` (values to hide) and `pinnedTextValueIds` (values to pin to specific positions).
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: array
                  items:
                    type: object
                    properties:
                      conceptId:
                        type: integer
                        description: the concept ID to create a filter for
                      settings:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - COLLECTION
                              - RANGE
                            description: the filter type
                          logic:
                            type: string
                            enum:
                              - AND
                              - OR
                            description: filter logic (for COLLECTION type)
                          showAbove:
                            type: integer
                            description: visibility threshold
                          sort:
                            type: string
                            description: 'sort order, e.g. ALPHANUMERIC'
                          position:
                            type: integer
                            description: display position
                      excludedTextValueIds:
                        type: array
                        description: text value IDs to exclude from the filter
                        items:
                          type: integer
                      pinnedTextValueIds:
                        type: array
                        description: text values to pin to specific positions
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            position:
                              type: integer
                settings:
                  type: object
                  description: global filter settings
                  properties:
                    sort:
                      type: string
                      description: 'default sort order for all filters, e.g. ALPHANUMERIC'
            example:
              filters:
                - conceptId: 18787
                  settings:
                    type: COLLECTION
                    logic: AND
                    showAbove: 80
                    sort: ALPHANUMERIC
                    position: 2
                  excludedTextValueIds:
                    - 18785
                  pinnedTextValueIds:
                    - id: 18769
                      position: 1
                - conceptId: 18781
                  settings:
                    type: RANGE
                    showAbove: 70
                    position: 1
              settings:
                sort: ALPHANUMERIC
    get:
      summary: Get filters
      tags:
        - Filters
      operationId: get-filters
      security:
        - apiKeyHeader: []
      parameters:
        - schema:
            type: boolean
            default: false
          name: fillConcepts
          in: query
          required: false
          description: 'If true, enriches each filter in the response with its full concept data from the ontology (name, view name, etc.).'
        - schema:
            type: boolean
            default: false
          name: slimConcepts
          in: query
          required: false
          description: 'If true (and fillConcepts is also true), returns a lighter concept representation.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  filterConfiguration:
                    type: object
                    properties:
                      projectId:
                        type: integer
                        description: the project ID
                      _id:
                        type: object
                        description: internal database ID
                        properties:
                          $oid:
                            type: string
                      filters:
                        type: array
                        description: list of configured filters
                        items:
                          type: object
                          properties:
                            conceptId:
                              type: integer
                              description: the concept ID that forms the filter
                            settings:
                              type: object
                              description: filter display and behavior settings
                              properties:
                                logic:
                                  type: string
                                  enum:
                                    - OR
                                    - AND
                                  description: filter logic — whether multiple selected values are combined with OR or AND
                                type:
                                  type: string
                                  enum:
                                    - RANGE
                                    - COLLECTION
                                    - NUMERIC_VALUES
                                    - BUCKET
                                    - COLOR
                                    - TREE
                                    - FLAT_TREE
                                    - BOOLEAN
                                  description: the filter type
                                sort:
                                  type: string
                                  enum:
                                    - ALPHANUMERIC
                                    - COUNT
                                    - USAGE
                                  description: sort order of filter options
                                showAbove:
                                  type: integer
                                  description: visibility threshold — filter is shown only if its count exceeds this value
                                position:
                                  type: integer
                                  description: display position of this filter
                                pinned:
                                  type: boolean
                                  nullable: true
                                  description: whether this filter is pinned
                                bucketCount:
                                  type: integer
                                  nullable: true
                                  description: number of buckets (for BUCKET type filters)
                                bucketFractionDigits:
                                  type: integer
                                  nullable: true
                                  description: number of decimal places for bucket boundaries
                                showFalseBoolean:
                                  type: boolean
                                  description: whether to show the false option for BOOLEAN type filters
                                maxFilterOptions:
                                  type: integer
                                  description: maximum number of filter options to return
                                  default: 1000
                                disableChildrenAutomatically:
                                  type: boolean
                                  description: applies to TREE type filters — whether child nodes are automatically disabled
                            pinnedTextValueIds:
                              type: array
                              description: text value IDs pinned to specific positions in the filter option list
                              items:
                                type: object
                                properties:
                                  id:
                                    type: integer
                                  position:
                                    type: integer
                            excludedTextValueIds:
                              type: array
                              description: text value IDs excluded from the filter
                              items:
                                type: integer
                            count:
                              type: integer
                              description: number of products matching this filter
                            valueCount:
                              type: array
                              description: per-value product counts
                              items:
                                type: object
                                properties:
                                  value:
                                    type: string
                                    description: the filter option value (text value ID name or numeric value)
                                  total:
                                    type: integer
                                    description: number of products with this value
                            visible:
                              type: boolean
                              description: whether the filter is visible in the frontend
                            filterGroupIds:
                              type: array
                              description: IDs of filter groups this filter belongs to
                              items:
                                type: integer
                      settings:
                        type: object
                        description: global filter configuration settings
                        properties:
                          sort:
                            type: string
                            enum:
                              - ALPHANUMERIC
                              - COUNT
                              - USAGE
                            description: default sort order for all filters
                          showAbove:
                            type: integer
                            description: global visibility threshold
                      filterGroups:
                        type: array
                        description: filter groups for grouping filters by category
                        items:
                          type: object
                          properties:
                            groupConceptId:
                              type: integer
                              description: concept ID of the group
                            position:
                              type: integer
                              description: display position of the group
                            visible:
                              type: boolean
                              description: whether this group is visible
                            filters:
                              type: array
                              description: filters in this group (same structure as top-level filters)
                              items:
                                type: object
                            categoryIds:
                              type: array
                              description: category IDs this group applies to
                              items:
                                type: integer
              example:
                status: success
                filterConfiguration:
                  projectId: 99999
                  _id:
                    $oid: aabbcc1122334455667788aa
                  filters:
                    - conceptId: 100000001
                      settings:
                        logic: OR
                        type: TREE
                        sort: ALPHANUMERIC
                        showAbove: 0
                        position: 0
                        pinned: null
                        bucketCount: null
                        bucketFractionDigits: null
                        showFalseBoolean: false
                        maxFilterOptions: 1000
                        disableChildrenAutomatically: true
                      pinnedTextValueIds:
                        - id: 100000101
                          position: 0
                        - id: 100000102
                          position: 1
                      excludedTextValueIds:
                        - 100000201
                        - 100000202
                      count: 17
                      valueCount:
                        - value: '$CAT-0001'
                          total: 5
                        - value: '$CAT-0002'
                          total: 12
                      visible: true
                      filterGroupIds: []
                    - conceptId: 100000002
                      settings:
                        logic: OR
                        type: COLLECTION
                        sort: ALPHANUMERIC
                        showAbove: 20
                        position: 1
                        pinned: null
                        bucketCount: null
                        bucketFractionDigits: null
                        showFalseBoolean: false
                        maxFilterOptions: 1000
                        disableChildrenAutomatically: true
                      pinnedTextValueIds: []
                      excludedTextValueIds: []
                      count: 34
                      valueCount:
                        - value: ATTR_A_text_attribute_#_1
                          total: 20
                        - value: ATTR_A_text_attribute_#_2
                          total: 14
                      visible: true
                      filterGroupIds: []
                    - conceptId: 100000003
                      settings:
                        logic: OR
                        type: RANGE
                        sort: ALPHANUMERIC
                        showAbove: 0
                        position: 2
                        pinned: null
                        bucketCount: null
                        bucketFractionDigits: null
                        showFalseBoolean: false
                        maxFilterOptions: 1000
                        disableChildrenAutomatically: true
                      pinnedTextValueIds: []
                      excludedTextValueIds: []
                      count: 45
                      valueCount:
                        - value: '1.5'
                          total: 8
                        - value: '3.0'
                          total: 15
                        - value: '6.0'
                          total: 22
                      visible: true
                      filterGroupIds: []
                    - conceptId: 100000004
                      settings:
                        logic: OR
                        type: BOOLEAN
                        sort: ALPHANUMERIC
                        showAbove: 0
                        position: 3
                        pinned: null
                        bucketCount: null
                        bucketFractionDigits: null
                        showFalseBoolean: true
                        maxFilterOptions: 1000
                        disableChildrenAutomatically: true
                      pinnedTextValueIds: []
                      excludedTextValueIds: []
                      count: 45
                      valueCount:
                        - value: 'true'
                          total: 45
                      visible: true
                      filterGroupIds: []
                  settings:
                    sort: ALPHANUMERIC
                    showAbove: 10
                  filterGroups: []
      description: |-
        Get all configured filters of a project.

        Returns the full filter configuration including each filter's settings, pinned/excluded values, value counts, and global settings.

        The `count` and `valueCount` fields reflect how many products match each filter and its individual values. How detailed these counts are depends on the **Compute Filter Counts** setting in [Search Studio → Product Filters](https://search.zoovu.com/filter/filters).

        Use `fillConcepts=true` to enrich the response with concept names and metadata from the ontology — useful for building a filter UI without a separate concept lookup.
  '/content':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    post:
      summary: Add or update content results
      tags:
        - Content
      operationId: add-or-update-content
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: OK
      description: |-
        Add or update content results. This can be used to insert e.g. category or brand pages which should come up in the search bar.

        Only up to 100 pages can be indexed at once. If you have more, call this endpoint multiple times.
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                    description: the URL of the content page
                  title:
                    type: string
                    description: the title of the content page
                  content:
                    type: string
                    description: the text content of the page
                  resultGroup:
                    type: string
                    description: the result group this content belongs to
                  imageUrl:
                    type: string
                    description: URL to an image for this content
                  dataPoints:
                    type: array
                    description: additional data points to display
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        value:
                          type: string
                        show:
                          type: boolean
                          description: whether to display this data point in search results
                  boost:
                    type: integer
                    description: boost factor for relevance ranking
            example:
              - url: 'https://test.com/1'
                title: test page testing 1
                content: test page for testing number 1
                resultGroup: first
                imageUrl: 'https://test.com/image.jpg'
                dataPoints:
                  - key: Name
                    value: Value
                    show: false
                  - key: Price
                    value: $3
                    show: true
                boost: 3
    delete:
      summary: Delete content results
      tags:
        - Content
      operationId: delete-content
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: OK
      description: |-
        Delete content results matching a URL pattern and/or older than a specific timestamp.
      parameters:
        - schema:
            type: integer
          name: projectId
          description: your Data Platform project ID
          in: query
          required: true
        - schema:
            type: string
          name: urlPattern
          description: 'regex pattern to match URLs to delete (e.g. ".*", "/blog/", "subdomain.example.com")'
          in: query
        - schema:
            type: integer
          name: lastUpdateTimeBefore
          description: 'Java milliseconds timestamp; content pages older than this value will be deleted'
          in: query
  '/project/check-credentials':
    parameters:
      - schema:
          type: integer
        name: projectId
        description: your Data Platform project ID
        in: query
        required: true
    get:
      summary: Check API credentials
      tags:
        - Accounting
      operationId: check-api-credentials
      security:
        - apiKeyHeader: []
      responses:
        '200':
          description: OK - credentials are valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
              example:
                status: success
                message: Successful authentication with apiKey.
        '401':
          description: Unauthorized - credentials are invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  code:
                    type: integer
                  message:
                    type: string
              example:
                status: failure
                code: 401
                message: Failed authentication with apiKey.
      description: Test your API credentials for validity. Returns a success response if the API key and project ID are valid.
components:
  schemas:
    FilterObject:
      type: object
      description: A filter object used in both `filters` and `preSetFilters` parameters.
      properties:
        name:
          type: string
          description: 'Display name of the filter attribute (e.g., "Color", "Price") — alternative to `conceptIdName` for identifying the filter attribute'
        conceptIdName:
          type: string
          description: 'The concept identifier (recommended way to identify the filter attribute)'
        id:
          type: integer
          description: 'The database concept ID — alternative to `conceptIdName` for identifying the filter attribute'
        key:
          type: string
          description: 'The database concept ID as a string — alternative to `conceptIdName` for identifying the filter attribute'
        type:
          type: string
          enum:
            - products
            - content
          description: 'Whether this filter applies to product results or content results. Filters for products and content cannot be mixed in the same request.'
        values:
          type: array
          description: 'For COLLECTION, COLOR, TREE filters: an array of filter values to match'
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: string
              conceptIdName:
                type: string
              id:
                type: integer
              key:
                type: integer
        min:
          type: number
          description: 'For RANGE filters: the minimum value'
        max:
          type: number
          description: 'For RANGE filters: the maximum value'
        booleanValue:
          type: boolean
          description: 'For BOOLEAN filters: the boolean value to filter by (true/false)'
        without:
          type: boolean
          description: 'When `true`, excludes products matching this filter instead of including them. Defaults to `false`.'
        allValues:
          type: boolean
          description: 'When `true`, matches all values of the attribute without specifying individual values.'
        logic:
          type: string
          enum:
            - AND
            - OR
          description: Sets the logical operator for multi-value filters.
    TaskInfo:
      type: object
      nullable: true
      description: Information about a task. Null if no task of this type has run.
      properties:
        _id:
          type: object
          properties:
            $oid:
              type: string
        projectId:
          type: integer
        projectName:
          type: string
          nullable: true
        origin:
          type: string
        taskStatus:
          type: string
          enum:
            - RUNNING
            - FINISHED
            - FAILED
        taskKind:
          type: string
        taskKindReadable:
          type: string
        failure:
          type: boolean
        message:
          type: string
        requestTime:
          type: integer
        requestTimeString:
          type: string
        startTime:
          type: integer
        startTimeString:
          type: string
        finishTime:
          type: integer
          nullable: true
        finishTimeString:
          type: string
          nullable: true
        nrOfItems:
          type: integer
        nrOfProcessedItems:
          type: integer
        progress:
          type: number
        logCounter:
          type: integer
    Product:
      type: object
      x-examples:
        Example 1:
          id: 67359595
          identifier: 120CP-UBDYBLPNC
          groupId: 120CP-UBDYBLPNC
          name: Dinghy Blunt Pinecone
          link: 'https://landyachtz.com/products/dinghy-blunt-pinecone'
          images:
            - url: 'https://landyachtz.com/cdn/shop/products/120CP-UBDYBLPNC-Dinghy_Blunt_-_Pinecone_-_Complete-Cruiser-Boards-Face-Web_1200x1200.jpg?v=1623457336'
              type: LARGE
          categories:
            - path:
                - Longboards
          facts:
            - attributeId: 263620226
              attribute: Canonical URL
              value: 'https://landyachtz.com/products/dinghy-blunt-pinecone'
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263620231
              attribute: price
              value: '199.99'
              type: NUMERIC_ATTRIBUTE
              unit: ''
              settings: []
            - attributeId: 263620230
              attribute: features
              valueId: 263620241
              value: Kicktail
              type: TEXT_ATTRIBUTE
              settings: []
            - attributeId: 263620223
              attribute: semantic-enhancement
              value: 'ubdyblpnc, 120c, 120 cp, web_1200x1200 jpg?v=1623457336, 1200 x, 120cp-ubdyblpnc, dinghy, web, 120cp, https, https://landyachtz com/cdn/shop/products/120cp, https://landyachtzcom/cdn/shop/products/120cp, 120cp-ubdyblpnc-dinghy, 120cp ubdyblpnc dinghy, htt, web_1200x1200jpg?v=1623457336, 120, https://landyachtz.com/cdn/shop/products/120cp, 1, web_1200x1200.jpg?v=1623457336, 1200, 120cpubdyblpncdinghy, http, 120cp ubdyblpnc, web_1, 120cpubdyblpnc, web_'
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263620230
              attribute: features
              valueId: 263620239
              value: LOW CAVE
              type: TEXT_ATTRIBUTE
              settings: []
            - attributeId: 263620233
              attribute: name
              value: Dinghy Blunt Pinecone
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263556687
              attribute: All Products
              value: 'TRUE'
              type: BOOLEAN_ATTRIBUTE
              settings: []
            - attributeId: 263620230
              attribute: features
              valueId: 263620237
              value: One Board One Tree
              type: TEXT_ATTRIBUTE
              settings: []
            - attributeId: 263620227
              attribute: description
              value: 'The Dinghy Blunt Pinecone Skateboard is an all purpose cruiser that pays homage to the conifer rich rainforests of the Pacific North West region in which we reside. Our Dinghy Blunt shape has a little extra width where you need it and a good amount of taper to allow for a more directional feel and some added room around the front foot. Matched up with slightly wider trucks than the Dinghy, this shape is great for riders with bigger feet or anyone looking for a little more stability and confidence out of their cruiser board. We opted for the slightly smaller Fatty Hawgs to make the Dinghy Blunt Pinecone easier to slide, ollie and live the all terrain life.'
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263620229
              attribute: _urlhash
              value: 73b4ef1161506160c93eb82bcac2a362c1fd2db0
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263620221
              attribute: _row-number
              value: '1'
              type: UNTYPED_ATTRIBUTE
              settings:
                - description
            - attributeId: 263765521
              attribute: Kicktail
              value: 'TRUE'
              type: BOOLEAN_ATTRIBUTE
              settings: []
            - attributeId: 263620230
              attribute: features
              valueId: 263620248
              value: SANDED WHEEL WELLS
              type: TEXT_ATTRIBUTE
              settings: []
            - attributeId: 263620230
              attribute: features
              valueId: 263620246
              value: 100% Canadian Maple
              type: TEXT_ATTRIBUTE
              settings: []
          lastUpdateTs: 1686054908546
      x-stoplight:
        id: p1ieggqcvk5pp
      properties:
        id:
          type: integer
          example: 1232
          description: Zoovu internal identifier
        identifier:
          type: string
          example: ABC-123
          description: your internally used product ID
        groupId:
          type: string
          example: DEF-213
          description: an identifier used to group variants of the same product
        name:
          type: string
          example: Flux Capacitor
          description: the product name
        link:
          type: string
          example: 'https://zoovu.com'
          description: URL to the product detail page
        images:
          type: array
          description: List of images
          items:
            type: object
            properties:
              url:
                type: string
                example: 'https://zoovu.com/wp-content/themes/zoovuthemev3/images/logo-blue.svg'
              type:
                type: string
                example: LARGE
        categories:
          type: array
          items:
            type: object
            properties:
              path:
                type: array
                description: the category path of the product
                items:
                  type: string
        facts:
          type: array
          items:
            type: object
            properties:
              attributeId:
                type: integer
                description: an internal Zoovu ID for the attribute
              attribute:
                type: string
                description: 'the attribute, e.g. "Brand" or "Price"'
              value:
                type: string
                description: 'the value, e.g. "Microsoft" or "799.99"'
              type:
                type: string
                description: 'the type of attribute, e.g. TEXT_ATTRIBUTE'
              settings:
                type: array
                items:
                  type: string
              valueId:
                type: integer
                description: an internal Zoovu ID for textual values
        lastUpdateTs:
          type: integer
          description: the last time the product was updated
    SearchResult:
      type: object
      properties:
        identifier:
          type: string
        groupId:
          type: string
        sxId:
          type: integer
        sxCategoryId:
          type: string
        dataPoints:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              key:
                type: string
              type:
                type: string
              value:
                type: string
              isCategory:
                type: boolean
              parsedValue:
                type: integer
              matched:
                type: boolean
        image:
          type: string
        name:
          type: string
        images:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              url:
                type: string
        link:
          type: string
        head:
          type: boolean
        relevance:
          type: integer
      x-examples:
        Example 1:
          identifier: '10030269'
          groupId: '10030269'
          sxId: 25015757
          sxCategoryId: CLASSICAL_GUITAR
          dataPoints:
            - id: 4714637
              key: Category
              type: PASS_ON
              value: 4/4 Size Classical Guitars
              isCategory: true
            - id: 4711258
              key: Brand Image
              type: PASS_ON
              value: 'https://media.justmusic.de/shop/images/hersteller/Hanika.jpg'
            - id: 4710490
              key: Brand
              type: PASS_ON
              value: HANIKA
            - id: 4710618
              key: Availability
              type: PASS_ON
              value: immediately available - delivery time 1-3 workdays
            - id: 4710493
              key: ArticleID
              type: PASS_ON
              value: '25062'
            - id: 4710596
              key: Short Description
              type: PASS_ON
              value: Classical guitar
            - id: 4711174
              key: Price
              type: PASS_ON
              value: €1699.00
              parsedValue: 1699
            - id: 4714637
              key: Category
              value: 4/4 Size Classical Guitars
              type: FILTER
            - id: 4710730
              key: Cutaway
              value: false
              type: FILTER
              matched: true
            - id: 4711174
              key: Price
              type: FILTER
              parsedValue: 1699
              value: 1699.00 €
              matched: true
          image: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/9175267_1.jpg
          name: Hanika 56 AF-N
          images:
            - type: ALTERNATIVE
              url: //media.justmusic.de/Artikelbilder/Shopsystem/1000px_V2/9175267_1.jpg
          link: //www.justmusic.de/en/Guitars-Basses/Classical-Guitars/4-4-Size-Classical-Guitars/Hanika-56-AF-N
          head: false
          relevance: 1000000
      description: 'A product as it is part of a search result, i.e. the product information is very restricted since the results are meant to be presented in a grid.'
      x-stoplight:
        id: l6u0rcnxojllf
    ProductInput:
      type: object
      properties:
        identifier:
          type: string
        groupIdentifier:
          type: string
        name:
          type: string
        productUrl:
          type: string
        categories:
          type: array
          items:
            type: object
            properties:
              path:
                type: array
                items:
                  type: string
        image:
          type: string
        attributes:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
              userGroups:
                type: array
                items:
                  type: string
      x-examples:
        Example 1:
          identifier: 6379b9_C
          groupIdentifier: '937'
          name: Garden Kitty Planter (Small) Typ C
          productUrl: 'https://www.tenthousandvillages.com/pet-parent/6379b95b7e4577dd7216dd13ae6ba0d4'
          categories:
            - path:
                - Home
                - Garden
                - Garden Maintainance
          image: 'https://www.tenthousandvillages.com/media/catalog/product/cache/1/small_image/100x100/9df78eab33525d08d6e5fb8d27136e95/6/6/6607890_1.jpg'
          attributes:
            - key: Price
              value: '5.99'
            - key: Price
              value: '3.99'
              userGroups:
                - '23'
            - key: Price
              value: '7.99'
              userGroups:
                - '42'
            - key: Made in
              value: Germany
              userGroups:
                - '23'
            - key: Color
              value: green
            - key: Description
              value: The Garden Kitty Planter is handcrafted in Bangladesh where makers from Corr-The Jute Works showcase their skill in ceramics by crafting each white-washed terracotta planter by hand.|The perfect pot for cat nip!
      x-stoplight:
        id: hq4pvlbqx74qu
    Project:
      type: object
      x-examples:
        Example 1:
          id: 8978
          name: some project name
          project-group-id: 1234
          project-group-name: some project group name
          tags:
            - tag1
            - tag2
      description: A project with a reference to the project group and all tags connected to the project
      properties:
        id:
          type: integer
        name:
          type: string
        project-group-id:
          type: integer
        project-group-name:
          type: string
        tags:
          type: array
          items:
            type: string
        locale:
          type: string
          x-stoplight:
            id: eakbllqduk1t5
      x-stoplight:
        id: yor5obb7mmqsi
    ErrorResponse:
      description: Payload for responses with HTTP Code 400
      properties:
        status:
          type: string
          example: failure
        code:
          type: integer
          example: 400
        message:
          type: string
          description: Provides more information why the error occured
          example: Your query params are not valid
      x-stoplight:
        id: e71rirne6wqkz
    ErrorConceptUpdateResponse:
      description: Payload for responses with HTTP Code 400
      x-stoplight:
        id: bhxb9zfibqymq
      type: object
      properties:
        status:
          type: string
          example: failure
        code:
          type: integer
          example: 400
        message:
          type: string
          description: Provides more information why the error occured
          example: Your query params are not valid
      x-examples:
        Example 1:
          status: failure
          code: 400
          message: Invalid Body
        Example 2:
          status: failure
          code: 400
          message: 'Incorrect request: Forbidden idName: CATEGORY Payload contains non-unique names: s,hj,jhkj'
    Concept:
      type: object
      x-stoplight:
        id: irhbxr5c5n1iu
      x-examples:
        Example 1:
          idName: BACKPACKS
          type: CATEGORY
          structuredViewData:
            url:
              link: 'https://example.com/aLinkToACategoryPage'
            passOnImage:
              link: 'https://example.com/image2.png'
            filterImage:
              link: 'https://example.com/image3.png'
          localization:
            de:
              name: Rucksäcke
            en:
              name: backpacks
              synonyms:
                - rucksacks
              extractionRules:
                - type: IS
                  text:
                    - type: MATCH
                      text: Hiking packs
          children:
            - idName: BACKPACKS/TREKKING
              type: CATEGORY
              localization:
                de:
                  name: Trekking
                en:
                  name: trekking
              children:
                - idName: BACKPACKS/TREKKING/WOMENS_TREKKING
                  type: CATEGORY
                  localization:
                    de:
                      name: Damen Trekking
                    en:
                      name: women's trekking
                      extractionRules:
                        - type: IS
                          text:
                            - type: CONTAINS
                              text: Women
                            - type: CONTAINS
                              text: trek
            - idName: BACKPACKS/NOTEBOOK
              type: CATEGORY
              localization:
                de:
                  name: Rucksäcke für Notebooks
                en:
                  name: notebook backpacks
      properties:
        idName:
          type: string
          description: "The idName is used as a unique identifier for a concept. \r\nThe idNames must come from your system, and are used in Data Platform to determine whether a concept needs to be created or updated."
        type:
          enum:
            - CATEGORY
            - NUMERIC_ATTRIBUTE
            - BOOLEAN_ATTRIBUTE
            - UNTYPED_ATTRIBUTE
            - TEXT_ATTRIBUTE
            - TEXT_VALUE
            - DATE_ATTRIBUTE
        description:
          type: string
          x-stoplight:
            id: wa8sy4y0r0rv1
          description: You can provide a descriptive text for your concepts.
        structuredViewData:
          type: object
          properties:
            url:
              type: object
              description: 'Allows you to define a URL for a concept. For example, you might provide landing pages for your category concepts.'
              properties:
                link:
                  type: string
                  x-stoplight:
                    id: nrgy81p7xx13p
                sourceType:
                  enum:
                    - AUTOMATIC
                    - MANUAL
                  description: 'The source type determines whether the concept data was manually or automatically provided. This cannot be set with the API request since API provided data is always considered automatic. When you receive the concepts from the API, however, you can distinguish between data provided or modified in the Data Platform manually and those provided or modified via the API.'
            passOnImage:
              type: object
              description: "Allows you to provide a URL to an image that can be shown in your experiences\r\nas part of the product tile."
              properties:
                link:
                  type: string
                  x-stoplight:
                    id: eiqfnu5fwi1o4
                sourceType:
                  enum:
                    - AUTOMATIC
                    - MANUAL
            filterImage:
              type: object
              description: Allows you to provide a URL to an image that can be shown when this concept is used as a filter option in your experiences.
              properties:
                link:
                  type: string
                  x-stoplight:
                    id: 2csjsm92bhzim
                sourceType:
                  enum:
                    - AUTOMATIC
                    - MANUAL
        localization:
          type: object
          properties:
            en:
              type: object
              description: |-
                Each localization object contains information about language-dependent names, synonyms, and extraction rules.

                For numeric attributes, you can also define a unit name. The unit name specifies how a numeric value should be displayed. In most cases, unit names are defined at the language level. However, if two locales share the same language but use different units for the same attribute, you can define the unit name at the locale level instead.

                **Examples:**

                Currencies: For the locale `fr-FR` (French, France), the currency is the Euro, while for `fr-CH` (French, Switzerland), the currency is the Swiss franc.

                Weights: For `en-US` (English, United States), weight is typically expressed in pounds (lbs), while for `en-CA` (English, Canada), it is expressed in kilograms (kg).

                When both are defined, the locale-specific unit name always overrides the language-specific unit name.

                Finally, note that the name, synonyms, and extractionRules must be defined at the language level and currently cannot be defined at the locale level.

                **Boolean attributes** also have unique fields. They support trueState and falseState, e.g., to define true as "Yes" and false as "No."

                Each localization object is referenced by a languageKey (defined by ISO 639-1).
              properties:
                name:
                  type: string
                  description: The name field represents the view name of an attribute/value/category for the given language
                unitName:
                  type: string
                  x-stoplight:
                    id: 5wxaes503i5aq
                  description: 'for numeric attributes, you may supply a unit. For example, unitName £ for price'
                synonyms:
                  type: array
                  description: "Each concept can have a set of language-dependent synonyms. Each synonym  is automatically \r\nused to improve search matches. "
                  items:
                    type: string
                trueState:
                  type: string
                  x-stoplight:
                    id: bmwclfgz8l7tf
                  description: 'for Boolean attributes you can provide the trueState. For example, the trueState for the Boolean attribute Availability could be "in stock."'
                falseState:
                  type: string
                  x-stoplight:
                    id: i8armrc2jkvob
                  description: 'for Boolean attributes you can provide the falseState. For example, the falseState for the Boolean attribute Availability could be "out of stock."'
                extractionRules:
                  type: array
                  description: 'Extraction rules are used to tell Data Platform from which inputs the defined concept should be extracted. '
                  items:
                    type: object
                    properties:
                      type:
                        enum:
                          - IS
                          - IS_NOT
                        description: "An extraction rule can be interpreted in two ways:\r\n- **IS**: If the rule matches the input, the concept is considered a match and should be extracted.\r\n- **IS_NOT**: If the rule matches the input, the concept should not be extracted.\r\n\r\nThis allows you to define more fine-grained rules and reduces false extractions."
                      text:
                        type: array
                        description: 'The array of text patterns defines what should or should not match. Each pattern in the array is combined using a logical AND, meaning that all patterns must match for the rule as a whole to be considered a match.'
                        items:
                          type: object
                          properties:
                            type:
                              description: "The text pattern supports 4 different types:\r\n\r\n``CONTAINS``: the text has to be contained in the input it is matched against, e.g. \r\n\"water\" is contained in \"waterproof\".\r\n\r\n``PHRASE_MATCH`` the whole word must be contained in the input, i.e. \r\n\"water\" would not be a PHRASE_MATCH in \"the device is waterproof\".\r\n\"waterproof\" however would be a PHRASE_MATCH since the whole word is contained.\r\n\r\n``MATCH`` means that the input has to be equal to the pattern, i.e.\r\n\"waterproof\" would not MATCH \"the device is waterproof\" but only the text pattern \r\n\"the device is waterproof\" would match. \r\n\r\n``REGEX`` allows to define complex regular expresions, e.g. the pattern\"\\d+\\sdays\" matches the input\r\n\"the battery lasts for 12 days\".\r\n\r\nAll patterns are case insensitive.\r\n"
                              enum:
                                - CONTAINS
                                - PHRASE_MATCH
                                - MATCH
                                - REGEX
                            text:
                              type: string
                      boolValue:
                        type: string
                        x-stoplight:
                          id: 6c9vlx2azh684
                        description: "Boolean attributes have an additional boolValue property that specifies whether the extraction rule should set the value to true or false based on the input.\r\n\r\nFor example, if you have a Boolean attribute called Availability, you might have the following extraction rule:\r\n\r\n```json\r\n{\r\n          \"type\": \"IS\",\r\n          \"text\": [\r\n            {\r\n              \"type\": \"MATCH\",\r\n              \"text\": \"availability\"\r\n            },\r\n            {\r\n              \"type\": \"MATCH\",\r\n              \"text\": \"out of stock\"\r\n            }\r\n          ],\r\n          \"boolValue\": \"FALSE\"\r\n        }\r\n```"
            en-US:
              type: object
              x-stoplight:
                id: ihx0h0qxdogge
              properties:
                unitName:
                  type: string
                  x-stoplight:
                    id: d3b34xe4rmoy9
                  description: 'Here you can define a unit specific to this locale, such as $ for price.'
        children:
          type: array
          description: 'Must be defined for categories and textual attributes with children (e.g., sub-categories or textual values)'
          items:
            type: object
            properties:
              idName:
                type: string
                x-stoplight:
                  id: cydpmetfsp32w
              type:
                type: string
                x-stoplight:
                  id: ddm5qdpetkdiu
                description: 'For child concepts, type will be either `CATEGORY` or `TEXT_VALUE`'
              description:
                type: string
                description: You can provide a descriptive text for your child concepts (e.g., value concepts or sub-categories).
              localization:
                type: object
                x-stoplight:
                  id: gnw1c4agjhfvv
                properties:
                  en:
                    type: object
                    x-stoplight:
                      id: d2r0h5ne838pz
                    description: "Each localization object contains information about language-dependent names, synonyms, and view names.\r\n\r\nEach localization object is referenced by a languageKey (defined by ISO 639-1)."
                    properties:
                      name:
                        type: string
                        x-stoplight:
                          id: 4d2lv62638snm
                      synonyms:
                        type: array
                        x-stoplight:
                          id: 9sznn6p35g02p
                        items:
                          x-stoplight:
                            id: 0y4gys4w0qp08
                          type: string
                      extractionRules:
                        type: array
                        x-stoplight:
                          id: cdxi4s9f7mnul
                        description: 'Extraction rules are used to tell Data Platform from which inputs the defined concept should be extracted.'
                        items:
                          x-stoplight:
                            id: sviftua0gmtc1
                          type: object
                          properties:
                            type:
                              enum:
                                - IS
                                - IS_NOT
                              description: "An extraction rule can be interpreted in two ways:\r\n- **IS**: If the rule matches the input, the concept is considered a match and should be extracted.\r\n- **IS_NOT**: If the rule matches the input, the concept should not be extracted.\r\n\r\nThis allows you to define more fine-grained rules and reduces false extractions."
                            text:
                              type: array
                              description: 'The array of text patterns defines what should or should not match. Each pattern in the array is combined using a logical AND, meaning that all patterns must match for the rule as a whole to be considered a match.'
                              items:
                                type: object
                                properties:
                                  type:
                                    description: "The text pattern supports 4 different types:\r\n\r\n``CONTAINS``: the text has to be contained in the input it is matched against, e.g. \r\n\"water\" is contained in \"waterproof\".\r\n\r\n``PHRASE_MATCH`` the whole word must be contained in the input, i.e. \r\n\"water\" would not be a PHRASE_MATCH in \"the device is waterproof\".\r\n\"waterproof\" however would be a PHRASE_MATCH since the whole word is contained.\r\n\r\n``MATCH`` means that the input has to be equal to the pattern, i.e.\r\n\"waterproof\" would not MATCH \"the device is waterproof\" but only the text pattern \r\n\"the device is waterproof\" would match. \r\n\r\n``REGEX`` allows to define complex regular expresions, e.g. the pattern\"\\d+\\sdays\" matches the input\r\n\"the battery lasts for 12 days\".\r\n\r\nAll patterns are case insensitive.\r\n"
                                    enum:
                                      - CONTAINS
                                      - PHRASE_MATCH
                                      - MATCH
                                      - REGEX
                                  text:
                                    type: string
        keyValuePairs:
          type: object
          x-stoplight:
            id: 6bil14gh68a4b
          description: "You can attach additional data to your concept in the form of key-value pairs.\r\n\r\nFor example,\r\n`{\r\n  \"keyValuePairs\": {\r\n    \"PIM-ID\": \"ABC-12345\",\r\n  }\r\n}`"
          properties:
            exampleKey:
              type: string
              x-stoplight:
                id: dk1ek5233h6w9
              description: Pass any key that you wish to attach to your concept with a string value.
    SuccessConceptUpdateResponse:
      type: object
      x-examples:
        Example 1:
          projectId: 35006
          projectName: null
          origin: LIVE-API
          taskStatus: PENDING
          name: ''
          taskIncrementType: ITEM_BASED
          failure: false
          requestTime: 1744122363132
          startTime: null
          finishTime: null
          progress: 0
          logCounter: 0
          id: 67f531fbfce78544d8621363
      properties:
        projectId:
          type: integer
        projectName:
          type: string
          nullable: true
        taskStatus:
          type: string
        requestTime:
          type: integer
        startTime:
          nullable: true
        finishTime:
          nullable: true
        progress:
          type: integer
        id:
          type: string
      x-stoplight:
        id: 86ynec049lvh0
  securitySchemes:
    apiKeyHeader:
      type: http
      scheme: bearer
      description: "Authorization: `Bearer <API key>`."
