---
updatedAt: 2026-05-28T22:55:39.000Z
agentTools:
  projectIndex: https://docs.constructor.com/llms.txt
---

# Update catalog

**🔐 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)`.

Send delta catalog files to replace the current catalog. You may upload up to three [files](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-catalog-file-upload-step-by-step-guide) in the form data under the following keys: `items`, `variations`, `item_groups`. If you do not wish to replace one of these types of resources then omit it from the request. Any records that already exist will be deleted and replaced with the records you provide in the files. Returns an identifier for a background [task](https://docs.constructor.com/reference/v1-tasks-retrieve-task).

**Related content**

* [Catalog file upload: step-by-step guide](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-catalog-file-upload-step-by-step-guide)
* [Catalog upload operations](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-upload-operations)
* [CSV feed upload via HTTP](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-csv-feed-upload-via-http)
* [CSV feed format - items (products)](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-csv-csv-feed-format-items-products)
* [CSV feed format - variations](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-csv-csv-feed-format-variations)
* [CSV feed format - item groups (categories)](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-csv-csv-feed-format-item-groups-categories)
* [JSON / JSONL feed format - items](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-json-jsonl-feed-format-items)
* [JSON / JSONL feed format - variations](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-json-jsonl-feed-format-variations)
* [JSON / JSONL feed format - item groups (categories)](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-json-jsonl-feed-format-item-groups-categories)

***

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "contact": {
      "email": "support@constructor.io"
    },
    "title": "Catalog management",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://ac.cnstrc.com"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Catalog"
    }
  ],
  "paths": {
    "/v1/catalog": {
      "patch": {
        "tags": [
          "Catalog"
        ],
        "operationId": "v1-catalog-update-catalog",
        "summary": "Update catalog",
        "description": "**🔐 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)).**\nFor authenticating with Bearer token, required scopes are: `catalog(w)`, `search_suggestions(w)`.\n\nSend delta catalog files to replace the current catalog. You may upload up to three [files](https://docs.constructor.com/docs/integrating-with-constructor-product-catalog-catalog-files-via-http-or-ftps-catalog-file-upload-step-by-step-guide) in the form data under the following keys: `items`, `variations`, `item_groups`. If you do not wish to replace one of these types of resources then omit it from the request. Any records that already exist will be deleted and replaced with the records you provide in the files. Returns an identifier for a background [task](https://docs.constructor.com/reference/v1-tasks-retrieve-task).",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "schema": {
              "title": "Key",
              "description": "The key of the index to use.",
              "maxLength": 100,
              "minLength": 1,
              "examples": [
                "key_K2pX7vBnU0bgA5xp"
              ],
              "type": "string"
            },
            "required": true
          },
          {
            "name": "section",
            "in": "query",
            "schema": {
              "title": "Section",
              "description": "The section of the index to use. Defaults to `Products`.",
              "maxLength": 100,
              "minLength": 1,
              "examples": [
                "Products",
                "Search Suggestions"
              ],
              "type": "string"
            },
            "required": false
          },
          {
            "name": "c",
            "in": "query",
            "schema": {
              "title": "Client ID",
              "description": "The ID of the client and version that the request is coming from, such as `cio-js-2.90`.",
              "maxLength": 100,
              "minLength": 1,
              "examples": [
                "cio-js-2.90",
                "cio-ios-1.0"
              ],
              "type": "string"
            },
            "required": false
          },
          {
            "name": "force",
            "in": "query",
            "schema": {
              "title": "Force",
              "description": "A flag to process the catalog even if it will invalidate a large part of existing data. By default, operations that would invalidate more than 50% of existing data are blocked unless `force=true` is used. Defaults to `False`.",
              "default": false,
              "examples": [
                false,
                true
              ],
              "type": "boolean"
            },
            "required": false
          },
          {
            "name": "notification_email",
            "in": "query",
            "schema": {
              "title": "Notification Email",
              "description": "The email address(es) to send a notification to if the task fails. Multiple addresses may be specified for multiple recipients.",
              "type": "array",
              "items": {
                "type": "string",
                "format": "email",
                "examples": [
                  "user@example.com"
                ]
              }
            },
            "required": false
          },
          {
            "name": "patch_delta",
            "in": "query",
            "schema": {
              "title": "Patch Delta",
              "description": "A flag to process updates as partial updates, meaning only provided fields will be updated in database. Fields not included in the upload or which are blank for a particular item will be ignored.",
              "default": false,
              "examples": [
                false,
                true
              ],
              "type": "boolean"
            },
            "required": false
          },
          {
            "name": "on_missing",
            "in": "query",
            "schema": {
              "description": "The strategy used to handle items that exist in the file and do not exist in the index. `IGNORE` silently ignores them and does not add them to the index, `CREATE` creates them, `FAIL` fails the ingestion. Can be set only when `patch_delta` is `true`. Default is `FAIL`.",
              "examples": [
                "IGNORE",
                "CREATE",
                "FAIL"
              ],
              "allOf": [
                {
                  "$ref": "#/components/schemas/MissingRecordsStrategy"
                }
              ]
            },
            "required": false
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "description": "File format of the uploaded items and variations files. Can be either `csv` or `jsonl`.",
              "default": "csv",
              "examples": [
                "csv",
                "jsonl"
              ],
              "allOf": [
                {
                  "$ref": "#/components/schemas/FileFormat"
                }
              ]
            },
            "required": false
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/CatalogPatchRequestBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogPatchResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogPatchAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation Error"
          },
          "401": {
            "description": "Credentials are not passed or action is forbidden."
          },
          "403": {
            "description": "The supplied token does not have the required permissions."
          },
          "429": {
            "description": "Rate limit breached"
          }
        },
        "security": [
          {
            "http_basic_auth": []
          },
          {
            "http_bearer_auth": [
              "catalog(w)",
              "search_suggestions(w)"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "FileFormat": {
        "title": "FileFormat",
        "enum": [
          "csv",
          "jsonl"
        ]
      },
      "MissingRecordsStrategy": {
        "title": "MissingRecordsStrategy",
        "enum": [
          "CREATE",
          "IGNORE",
          "FAIL"
        ]
      },
      "CatalogPatchRequestBody": {
        "title": "CatalogPatchRequestBody",
        "type": "object",
        "properties": {
          "items": {
            "title": "Items",
            "description": "File with items in CSV or JSONL format",
            "type": "string",
            "format": "binary"
          },
          "variations": {
            "title": "Variations",
            "description": "File with variations in CSV or JSONL format",
            "type": "string",
            "format": "binary"
          },
          "item_groups": {
            "title": "Item Groups",
            "description": "File with item groups in CSV or JSONL format",
            "type": "string",
            "format": "binary"
          }
        }
      },
      "CatalogPatchResponse": {
        "title": "CatalogPatchResponse",
        "type": "object",
        "properties": {
          "task_id": {
            "title": "Task Id",
            "description": "Task ID for the ingestion job",
            "type": "integer"
          },
          "task_status_path": {
            "title": "Task Status Path",
            "description": "Path to check the status of the ingestion job",
            "type": "string"
          }
        },
        "required": [
          "task_id",
          "task_status_path"
        ]
      },
      "CatalogPatchAcceptedResponse": {
        "title": "CatalogPatchAcceptedResponse",
        "type": "object",
        "properties": {
          "message": {
            "title": "Message",
            "description": "Info message",
            "type": "string"
          }
        },
        "required": [
          "message"
        ]
      }
    },
    "securitySchemes": {
      "http_basic_auth": {
        "type": "http",
        "scheme": "basic"
      },
      "http_bearer_auth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```