Coveo Facet Field Configurations API

openapi: 3.0.1
info:
  title: Coveo Activity Activities Facet Field Configurations API
  description: API for Coveo Platform
  termsOfService: https://www.coveo.com/en/support/terms-agreements
  contact:
    name: Coveo
    url: https://connect.coveo.com/s/discussions
  version: 1.0.0
servers:
- url: https://platform.cloud.coveo.com
  description: Coveo public API endpoint
security:
- oauth2:
  - full
tags:
- name: Facet Field Configurations
paths:
  /rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields/bulk-update:
    put:
      tags:
      - Facet Field Configurations
      summary: Update Multiple Facet Fields
      description: 'Updates multiple facet fields.Maximum 100 items per request.</br></br>**Required privilege:** Merchandising Hub - Edit<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}

        ```

        </details>'
      operationId: bulkUpdate
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: path
        description: The unique identifier of the tracking target.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                oneOf:
                - $ref: '#/components/schemas/ContinuousFacetFieldModel'
                - $ref: '#/components/schemas/HierarchicalFacetFieldModel'
                - $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
                - $ref: '#/components/schemas/RegularFacetFieldModel'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/ContinuousFacetFieldModel'
                  - $ref: '#/components/schemas/HierarchicalFacetFieldModel'
                  - $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
                  - $ref: '#/components/schemas/RegularFacetFieldModel'
      x-pretty-name: bulkUpdate
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields/bulk-update_put
  /rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields/bulk-create:
    post:
      tags:
      - Facet Field Configurations
      summary: Creates Multiple Facet Fields
      description: 'Creates multiple facet fields. Maximum 100 items per request.</br></br>**Required privilege:** Merchandising Hub - Edit<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"EDIT","targetId":"{trackingId}"}

        ```

        </details>'
      operationId: bulkCreate
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: path
        description: The unique identifier of the tracking target.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                oneOf:
                - $ref: '#/components/schemas/ContinuousFacetFieldModel'
                - $ref: '#/components/schemas/HierarchicalFacetFieldModel'
                - $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
                - $ref: '#/components/schemas/RegularFacetFieldModel'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/ContinuousFacetFieldModel'
                  - $ref: '#/components/schemas/HierarchicalFacetFieldModel'
                  - $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
                  - $ref: '#/components/schemas/RegularFacetFieldModel'
      x-pretty-name: bulkCreate
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: EDIT
        targetId: '{trackingId}'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields/bulk-create_post
  /rest/organizations/{organizationId}/commerce/v2/tracking-ids/{trackingId}/facet/fields:
    get:
      tags:
      - Facet Field Configurations
      summary: Retrieves All Facet Fields
      description: 'Retrieve all facet fields.</br></br>**Required privilege:** Merchandising Hub - View<br /><br /><details><summary>Privilege required</summary>

        ```

        {"owner":"COMMERCE","targetDomain":"MERCHANDISING_HUB","type":"VIEW","targetId":"*"}

        ```

        </details>'
      operationId: getAll_1
      parameters:
      - name: organizationId
        in: path
        description: The unique identifier of the target [organization](https://docs.coveo.com/en/185/).<br />**Example:** `acmecorporation8tp8wu3`
        required: true
        schema:
          type: string
      - name: trackingId
        in: path
        description: The unique identifier of the tracking target.
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The 0-based index number of the page to retrieve.
        required: false
        schema:
          minimum: 0
          type: integer
          format: int32
          default: 0
      - name: perPage
        in: query
        description: The number of items to return per page.
        required: false
        schema:
          maximum: 100
          minimum: 1
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/PaginatedResponseFacetFieldModel'
      x-pretty-name: getAll
      x-required-privilege:
        owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-required-privileges:
      - owner: COMMERCE
        targetDomain: MERCHANDISING_HUB
        type: VIEW
        targetId: '*'
      x-ui-operation-id: /rest/organizations/paramId/commerce/v2/tracking-ids/paramId/facet/fields_get
components:
  schemas:
    HierarchicalFacetFieldModel:
      required:
      - displayNames
      - field
      - initialNumberOfValues
      - sortCriteria
      type: object
      allOf:
      - $ref: '#/components/schemas/FacetFieldModel'
      - type: object
        properties:
          id:
            type: string
            description: The unique identifier of the facet field configuration.
            format: uuid
            example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
          field:
            maxLength: 255
            minLength: 0
            type: string
            description: The name of the underlying index field. This property can't be updated after creation.
            example: ec_category
          type:
            type: string
            description: The type of the facet field.
            example: HIERARCHICAL
            enum:
            - REGULAR
            - CONTINUOUS
            - NUMERICAL_RANGES
            - HIERARCHICAL
          displayNames:
            uniqueItems: true
            type: array
            description: A list of localized display names for the facet field. When a localized display name is not provided for a given language, the index non-localized display name is used. If a non-localized display name is not configured, the index field name is used.
            items:
              $ref: '#/components/schemas/LocalizedValueModel'
          injectionDepth:
            minimum: 1000
            type: integer
            description: "The maximum number of items to scan for facet values.\n<br/>When value is not provided:<br/>\n    <ul>\n        <li>Creation: defaults to `1000`</li>\n        <li>Update: preserves existing database value</li>\n    </ul>\n"
            format: int32
            default: 1000
          sortCriteria:
            type: string
            description: The criteria used to sort facet field values.
            example: relevance
            enum:
            - RELEVANCE
            - ALPHANUMERIC
            - OCCURRENCES
          initialNumberOfValues:
            maximum: 200
            minimum: 1
            type: integer
            description: The initial number of facet values shown.
            format: int32
          useInFilterSuggestions:
            type: boolean
            description: Whether the facet field can be used in filter suggestions. See [here](https://docs.coveo.com/en/o8ce0240#headless-implementation) for more guidance.
    LocalizedValueModel:
      required:
      - language
      - value
      type: object
      properties:
        language:
          minLength: 1
          type: string
          description: An ISO 639-1 language code.
          example: en
        value:
          type: string
          description: The localized value
          example: Hello
      description: A list of localized display names for the facet field. When a localized display name is not provided for a given language, the index non-localized display name is used. If a non-localized display name is not configured, the index field name is used.
    ManualNumericalRangesDetailsModel:
      required:
      - ranges
      type: object
      allOf:
      - $ref: '#/components/schemas/NumericalRangesDetailsModel'
      - type: object
        properties:
          type:
            type: string
            description: The type of numerical range.
            example: MANUAL
            enum:
            - AUTOMATIC_EVEN
            - MANUAL
          ranges:
            minItems: 1
            type: array
            items:
              $ref: '#/components/schemas/NumericalRangeModel'
    NumericalRangesDetailsModel:
      type: object
      properties:
        type:
          type: string
          enum:
          - AUTOMATIC_EVEN
          - MANUAL
      discriminator:
        propertyName: type
    PaginatedResponseFacetFieldModel:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        items:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ContinuousFacetFieldModel'
            - $ref: '#/components/schemas/HierarchicalFacetFieldModel'
            - $ref: '#/components/schemas/NumericalRangesFacetFieldModel'
            - $ref: '#/components/schemas/RegularFacetFieldModel'
    NumericalRangeModel:
      type: object
      properties:
        start:
          type: number
          format: double
        end:
          type: number
          format: double
    FacetFieldModel:
      type: object
      properties:
        type:
          type: string
          enum:
          - REGULAR
          - CONTINUOUS
          - NUMERICAL_RANGES
          - HIERARCHICAL
      discriminator:
        propertyName: type
    AutomaticEvenNumericalRangesDetailsModel:
      required:
      - numberOfRanges
      type: object
      allOf:
      - $ref: '#/components/schemas/NumericalRangesDetailsModel'
      - type: object
        properties:
          type:
            type: string
            description: The type of numerical range.
            example: AUTOMATIC_EVEN
            enum:
            - AUTOMATIC_EVEN
            - MANUAL
          numberOfRanges:
            maximum: 10
            minimum: 2
            type: integer
            description: The number of ranges to generate.
            format: int32
            example: 4
    LocalizedPinnedFacetValuesModel:
      required:
      - language
      - values
      type: object
      properties:
        language:
          minLength: 1
          type: string
          description: The IETF language tag for which the pinned values applies.
          example: en
        values:
          maxItems: 100
          minItems: 0
          type: array
          description: Identifies the facet values that must appear at the top, in this order. Facet values that are not pinned will be sorted according to the `sortCriteria`.
          example:
          - Small
          - Medium
          - Large
          items:
            minLength: 1
            type: string
            description: Identifies the facet values that must appear at the top, in this order. Facet values that are not pinned will be sorted according to the `sortCriteria`.
            example: '["Small","Medium","Large"]'
      description: A list of pinned facet values. Pinned values are always shown at the top of the facet in the provided order when there is at least one product that matches the pinned value.
      default: []
    ContinuousFacetFieldModel:
      required:
      - displayNames
      - field
      type: object
      allOf:
      - $ref: '#/components/schemas/FacetFieldModel'
      - type: object
        properties:
          id:
            type: string
            description: The unique identifier of the facet field configuration.
            format: uuid
            example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
          field:
            maxLength: 255
            minLength: 0
            type: string
            description: The name of the underlying index field. This property can't be updated after creation.
            example: ec_price
          type:
            type: string
            description: The type of the facet field.
            example: CONTINUOUS
            enum:
            - REGULAR
            - CONTINUOUS
            - NUMERICAL_RANGES
            - HIERARCHICAL
          displayNames:
            uniqueItems: true
            type: array
            description: A list of localized display names for the facet field. When a localized display name is not provided for a given language, the index non-localized display name is used. If a non-localized display name is not configured, the index field name is used.
            items:
              $ref: '#/components/schemas/LocalizedValueModel'
          injectionDepth:
            minimum: 1000
            type: integer
            description: "The maximum number of items to scan for facet values.\n<br/>When value is not provided:<br/>\n    <ul>\n        <li>Creation: defaults to `1000`</li>\n        <li>Update: preserves existing database value</li>\n    </ul>\n"
            format: int32
            default: 1000
    NumericalRangesFacetFieldModel:
      required:
      - displayNames
      - field
      - rangeDetails
      type: object
      allOf:
      - $ref: '#/components/schemas/FacetFieldModel'
      - type: object
        properties:
          id:
            type: string
            description: The unique identifier of the facet field configuration.
            format: uuid
            example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
          field:
            maxLength: 255
            minLength: 0
            type: string
            description: The name of the underlying index field. This property can't be updated after creation.
            example: ec_price
          type:
            type: string
            description: The type of the facet field.
            example: NUMERICAL_RANGES
            enum:
            - REGULAR
            - CONTINUOUS
            - NUMERICAL_RANGES
            - HIERARCHICAL
          displayNames:
            uniqueItems: true
            type: array
            description: A list of localized display names for the facet field. When a localized display name is not provided for a given language, the index non-localized display name is used. If a non-localized display name is not configured, the index field name is used.
            items:
              $ref: '#/components/schemas/LocalizedValueModel'
          injectionDepth:
            minimum: 1000
            type: integer
            description: "The maximum number of items to scan for facet values.\n<br/>When value is not provided:<br/>\n    <ul>\n        <li>Creation: defaults to `1000`</li>\n        <li>Update: preserves existing database value</li>\n    </ul>\n"
            format: int32
            default: 1000
          rangeDetails:
            oneOf:
            - $ref: '#/components/schemas/AutomaticEvenNumericalRangesDetailsModel'
            - $ref: '#/components/schemas/ManualNumericalRangesDetailsModel'
    RegularFacetFieldModel:
      required:
      - displayNames
      - field
      - initialNumberOfValues
      - pinnedValues
      - sortCriteria
      type: object
      allOf:
      - $ref: '#/components/schemas/FacetFieldModel'
      - type: object
        properties:
          id:
            type: string
            description: The unique identifier of the facet field configuration.
            format: uuid
            example: 755e2dd8-3a8f-19fb-b9ed-ed89c4f83c3b
          field:
            maxLength: 255
            minLength: 0
            type: string
            description: The name of the underlying index field. This property can't be updated after creation.
            example: ec_brand
          type:
            type: string
            description: The type of the facet field.
            example: REGULAR
            enum:
            - REGULAR
            - CONTINUOUS
            - NUMERICAL_RANGES
            - HIERARCHICAL
          displayNames:
            uniqueItems: true
            type: array
            description: A list of localized display names for the facet field. When a localized display name is not provided for a given language, the index non-localized display name is used. If a non-localized display name is not configured, the index field name is used.
            items:
              $ref: '#/components/schemas/LocalizedValueModel'
          injectionDepth:
            minimum: 1000
            type: integer
            description: "The maximum number of items to scan for facet values.\n<br/>When value is not provided:<br/>\n    <ul>\n        <li>Creation: defaults to `1000`</li>\n        <li>Update: preserves existing database value</li>\n    </ul>\n"
            format: int32
            default: 1000
          sortCriteria:
            type: string
            description: The criteria used to sort facet field values.
            example: relevance
            default: RELEVANCE
            enum:
            - RELEVANCE
            - ALPHANUMERIC
            - OCCURRENCES
          initialNumberOfValues:
            maximum: 1000
            minimum: 1
            type: integer
            description: The initial number of facet values shown.
            format: int32
            default: 8
          useInFilterSuggestions:
            type: boolean
            description: Whether the facet field can be used in filter suggestions. See [here](https://docs.coveo.com/en/o8ce0240#headless-implementation) for more guidance.
          resultsMustMatch:
            type: string
            description: "Specifies how a result must match the selected values.\n<br/>When value is not provided:<br/>\n    <ul>\n        <li>Creation: defaults to `AT_LEAST_ONE_VALUE`</li>\n        <li>Update: preserves existing database value</li>\n    </ul>\n"
            example: AT_LEAST_ONE_VALUE
            enum:
            - AT_LEAST_ONE_VALUE
            - ALL_VALUES
          pinnedValues:
            type: array
            description: A list of pinned facet values. Pinned values are always shown at the top of the facet in the provided order when there is at least one product that matches the pinned value.
            items:
              $ref: '#/components/schemas/LocalizedPinnedFacetValuesModel'
            default: []
    Pagination:
      type: object
      properties:
        page:
          type: integer
          format: int32
        perPage:
          type: integer
          format: int32
        totalItems:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://platform.cloud.coveo.com/oauth/authorize
          tokenUrl: https://platform.cloud.coveo.com/oauth/token
          scopes:
            full: required