---
title: "Create or replace items"
method: PUT
path: "/v2/items"
tags: ["Items"]
---

# Create or replace items

`PUT /v2/items`

## Request

- Base URL: `https://ac.cnstrc.com`
- URL: `https://ac.cnstrc.com/v2/items`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

**🔐 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: `catalog(w)`, `search_suggestions(w)`.

Create items or replace the data of existing items. Returns an identifier for a background [task](/reference/v1-tasks-retrieve-task).

## Query parameters

- `key` string, required: The key of the index to use.
- `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`.
- `force` boolean: A flag to process the catalog even if it will invalidate a large part of existing data. Defaults to `False`.
- `notification_email` string[]: The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.

## Request body

- ItemListPutRequestBody
  - `items` Item[], required: Array of items you want to create or replace.
    - `id` string, required: The ID of the item, must be unique.
    - `name` string, required: The name of the item, as it will appear in the results. Must contain at least one alphanumeric character.
    - `suggested_score` integer: A number that will influence the item's initial ranking relative to other item scores (the higher the score, the higher in the list of suggestions the item will appear).
    - `data` ItemMetadata: Additional data about item. In addition to the listed properties you can also provide any other information you want to associate with that item. No special validation is made for that data.
      - `keywords` string[]: An array of keywords for this item. Keywords are useful if you want a product name to appear when a user enters a search term that isn't in the product name itself.
      - `url` string: A URL to directly send the user after selecting the item. Might be required in some cases. Please contact support@constructor.io if you have questions around that.
      - `image_url` string: A URL that points to an image you'd like displayed next to some item (only applicable when url is supplied).
      - `facets` Facets
      - `group_ids` string[]: You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please contact support@constructor.io group_ids can be used as filters in search, autosuggest, and browse requests.
      - `description` string: A description for this item. The maximum length of this field is 4000 characters.
      - `active` boolean
      - `__cnstrc_release_time` union: Date and time of item's release, useful to hide items from search results until its official release.
        - string, date-time
        - integer
        - number
      - `__cnstrc_expiration_time` union: Date and time of item's expiration, useful to hide items from search results at and after a scheduled time.
        - string, date-time
        - integer
        - number

## Response `200`

OK

- ItemListPutResponse
  - `task_id` integer, required
  - `task_status_path` string, required

## Other responses

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

---

[API](https://skmtc.dev/constructor/apis/catalog-management.md) - [All operations](https://skmtc.dev/constructor/apis/catalog-management/llms.txt) - [OpenAPI document](https://skmtc.dev/constructor/apis/catalog-management/revisions/3a9833796fc6?raw)