---
title: "Create or replace refined collection"
method: PUT
path: "/v1/refined_collections/{collection_id}"
tags: ["Searchandising for Collections"]
---

# Create or replace refined collection

`PUT /v1/refined_collections/{collection_id}`

**🔐 This endpoint requires [HTTP authentication](https://docs.constructor.com/reference/main-authentication) (either [Basic](https://docs.constructor.com/reference/main-authentication#basic-authentication) or [Bearer](https://docs.constructor.com/reference/main-authentication#bearer-authentication)).**
For authenticating with Bearer token, required scopes are: `searchandising.refined_collections(w)`.

Create or replace a refined collection. It will replace all existing rules associated with the collection if there are any. It will also flip `allow_automatic_rules` to `true` (which is default) if attribute's value isn't submitted in the request.

## Path parameters

- `collection_id` string, required

## Query parameters

- `key` string, required — The key of the index to use.
- `response_section` 'results' | 'facets'
- `section` string — The section of the index to use. Defaults to `Products`.
- `c` string — The ID of the client and version that the request is coming from, such as `cio-js-2.90`.

## Request body

- RefinedCollectionPutBody
  - `slot_rules` SlotRuleBase[] — The slotting rules attached to the refined filter
    - `request_filters` object — Facet conditions for the rule to be applied.
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` SlotRuleParameters, required
      - `item_id` string, required — The ID of an item to place in position.
      - `variation_slice` object — The variation slice ID of that item to use for slotting.
      - `position` integer, required — The position of item to place in.
      - `fuzzy_match` boolean — The flag to determine if the rule should be applied only when there's an exact query match. Warning: usage of this parameter has been deprecated - please contact Constructor support for assistance.
      - `labels` object — Can be used to add other miscellaneous properties for the item.
    - `rule_type` 'slot'
  - `whitelist_rule` WhitelistRuleBase
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` WhitelistFiltersRuleParameters, required
      - `filters` FiltersDict, required
    - `rule_type` 'whitelist'
  - `blacklist_rules` BlacklistRuleBase[] — The blacklist rules attached to the refined filter
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` ItemIdsOrFilters, required
      - `filters` FiltersDict
      - `item_ids` string[] — The IDs of the items to be recalled.
    - `rule_type` 'blacklist'
  - `boost_rules` BoostRuleBase[] — The boost rules attached to the refined filter. It is allowed to create maximum 50 manual and 50 automatic rules. The number of rules for each of the types includes both active and inactive rules
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` BoostRuleDict, required
      - `filters` FiltersDict
      - `item_ids` string[] — The IDs of the items to be recalled.
      - `boost` number, required — Boost factor for this rule.
    - `rule_type` 'boost'
  - `content_rules` ContentRuleBase[] — The content rules attached to the refined filter
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` ContentRuleParameters, required
      - `data` object, required — The data inside the content rule.
    - `rule_type` 'content'
  - `variation_slicing_rule` VariationSlicingRuleBase
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` VariationSlicingRuleParameters, required
      - `facet_names` string[], required — The facet which we will slice based on.
      - `filter_expression` union
        - object
        - string, json
    - `rule_type` 'variation_slicing'
  - `filters_slot_rules` FiltersSlotRuleBase[] — The filters slot rules attached to the refined filter
    - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
    - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
    - `active` boolean — Indicates whether this rule is active or not.
    - `start_time` string, date-time — Date and time when the rule should be enabled.
    - `end_time` string, date-time — Date and time when the rule should be disabled.
    - `campaign_id` integer
    - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
    - `rule` FiltersSlotRuleParameters, required
      - `filters` FiltersDict
      - `filter_expression` union
        - object
        - string, json
      - `position_ranges` PositionRange[], required — A list of ranges of positions to place the items.
        - `start` integer, required — The start position of the slot.
        - `end` integer, required — The end position of the slot.
      - `labels` object — Can be used to add other miscellaneous properties for the item.
    - `rule_type` 'filters_slot'
  - `allow_automatic_rules` boolean — Specifies whether to allow automatic creation of rules
  - `last_reviewed_at` string, date-time — The date of the last review
  - `last_reviewed_by` string — The user who last reviewed the refined filter
  - `next_review_at` string, date-time — The date of the next review

## Response `200`

OK

- union
  - RefinedCollectionResultsResponse
    - `collection_id` string, required
    - `allow_automatic_rules` boolean, required
    - `slot_rules` SlotRuleResponse[], required
      - `request_filters` object — Facet conditions for the rule to be applied.
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` SlotRuleParameters, required
        - `item_id` string, required — The ID of an item to place in position.
        - `variation_slice` object — The variation slice ID of that item to use for slotting.
        - `position` integer, required — The position of item to place in.
        - `fuzzy_match` boolean — The flag to determine if the rule should be applied only when there's an exact query match. Warning: usage of this parameter has been deprecated - please contact Constructor support for assistance.
        - `labels` object — Can be used to add other miscellaneous properties for the item.
      - `rule_type` 'slot', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `whitelist_rule` WhitelistRuleResponse
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` WhitelistFiltersRuleParameters, required
        - `filters` FiltersDict, required
      - `rule_type` 'whitelist', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `blacklist_rules` BlacklistRuleResponse[], required
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` ItemIdsOrFilters, required
        - `filters` FiltersDict
        - `item_ids` string[] — The IDs of the items to be recalled.
      - `rule_type` 'blacklist', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `boost_rules` BoostRuleResponse[], required
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` BoostRuleDict, required
        - `filters` FiltersDict
        - `item_ids` string[] — The IDs of the items to be recalled.
        - `boost` number, required — Boost factor for this rule.
      - `rule_type` 'boost', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `content_rules` ContentRuleResponse[], required
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` ContentRuleParameters, required
        - `data` object, required — The data inside the content rule.
      - `rule_type` 'content', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `filters_slot_rules` FiltersSlotRuleResponse[], required
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` FiltersSlotRuleParameters, required
        - `filters` FiltersDict
        - `filter_expression` union
          - object
          - string, json
        - `position_ranges` PositionRange[], required — A list of ranges of positions to place the items.
          - `start` integer, required — The start position of the slot.
          - `end` integer, required — The end position of the slot.
        - `labels` object — Can be used to add other miscellaneous properties for the item.
      - `rule_type` 'filters_slot', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `variation_slicing_rule` VariationSlicingRuleResponse
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` VariationSlicingRuleParameters, required
        - `facet_names` string[], required — The facet which we will slice based on.
        - `filter_expression` union
          - object
          - string, json
      - `rule_type` 'variation_slicing', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
  - RefinedFilterFacetsResponse
    - `id` integer, required
    - `filter_name` string, required
    - `filter_value` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `last_updated_internally` string, date-time
    - `last_updated_externally` string, date-time
    - `last_reviewed_at` string, date-time
    - `last_reviewed_by` string
    - `next_review_at` string, date-time
    - `allow_automatic_rules` boolean, required
    - `slot_rules` SlotFacetRuleResponse[], required
      - `target` 'facet_group' | 'facet_option', required
      - `facet_group_name` string
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` SlotFacetRuleParameters, required
        - `name` string, required — The name of the facet to place in position.
        - `position` integer, required — The position of facet to place in.
      - `rule_type` 'slot', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.
    - `blacklist_rules` BlacklistFacetRuleResponse[], required
      - `target` 'facet_group' | 'facet_option', required
      - `facet_group_name` string
      - `id` integer, required — The ID of the rule, must be unique.
      - `request_tag_name` 'client_ip' | 'client_version' | 'geo_city' | 'geo_country' | 'geo_country_iso_code' | 'geo_region' | 'dt_weekday' | 'dt_timeofday' | 'user_segment' | 'autogenerated_user_segment' | 'dynamic_segment'
      - `request_tag_value` string — Request tag value to be used to activate this entity for, used only with request_tag_name.
      - `active` boolean — Indicates whether this rule is active or not.
      - `start_time` string, date-time — Date and time when the rule should be enabled.
      - `end_time` string, date-time — Date and time when the rule should be disabled.
      - `campaign_id` integer
      - `automatically_generated` boolean — Boolean to indicate if this rule is automatically generated or not.
      - `rule` BlacklistFacetRuleParameters, required
        - `name` string, required — The name of the facet to block.
      - `rule_type` 'blacklist', required
      - `created_at` string, date-time — Date & time in ISO 8601 format for the creation of this rule.
      - `updated_at` string, date-time — Date & time in ISO 8601 format for last update for this rule.

## Other responses

- `400` — Validation Error
- `401` — Credentials are not passed or action is forbidden.
- `403` — The supplied token does not have the required permissions.
- `429` — Rate limit breached

---

[API](https://skmtc.dev/constructor/apis/autocomplete.md) · [All operations](https://skmtc.dev/constructor/apis/autocomplete/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/constructor/autocomplete/revisions/2d33330633b6/schema)