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

# Create or replace items

`PUT /v2/items`

**🔐 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, nullable — 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 metadata for an item.
      - `keywords` string[], nullable — 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 is not in the product name itself.
      - `url` string, nullable — A URL to directly send the user after selecting the item. Might be required in some cases. Please consult with your integration team for more information.
      - `image_url` string, nullable — A URL that points to an image you would like displayed next to some item (only applicable when URL is supplied).
      - `group_ids` string[], nullable — You can associate each item with one or more groups (i.e. categories). To set up a group hierarchy please consult with your integration team for more information. `group_ids` can be used as filters in search, autosuggest, and browse requests.
      - `description` string, nullable — A description for this item. The maximum length of this field is 4,000 characters.
      - `active` boolean, nullable — Determines whether the item is active and eligible to be returned in results.
      - `facets` object, nullable — A mapping of facet names to values. Each value is either a single string, integer, or floating point number, or a list of those. Facet keys are limited to 100 characters; string values are limited to 200 characters.

## 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/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)