> For the complete documentation index, see [llms.txt](https://doc.batch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.batch.com/developer/api/cep/catalogs/replace-start.md). # Replace start {% hint style="info" %} **Beta.** Catalog replace is a Beta feature and its API surface may change before GA. You must send the `Batch-Beta: catalog-replace` header with each replace call. {% endhint %} Use `/catalogs/replace/start` to open a replace session on a catalog that exists. A replace changes all the contents of a catalog in one atomic operation. It can also change the schema. Batch adds the new items to a hidden revision, and the current revision continues to serve reads at the same time. This means that any campaign or automation relying on the catalog never sees an empty or partly filled catalog. The switch happens only when you complete the replace. ## Replace Start > \*\*Beta.\*\* Catalog replace is a Beta feature and can change. Send the \`Batch-Beta: catalog-replace\` header on each call.\ > \
\
Opens a replace session on an existing catalog. A replace changes the entire contents of a catalog, and optionally its schema, in one atomic operation. Batch adds the new items to a hidden revision. The current revision continues to serve reads at the same time. Thus campaigns do not see an empty or a partly filled catalog.\ > \
\
Send the new items to \`/catalogs/replace/items\`. Then apply them with \`/catalogs/replace/complete\`, or discard them with \`/catalogs/replace/cancel\`. Each catalog can have only one open session at a time. The response gives a \`replace\_token\`. Send this token in each subsequent call to identify the session.
```json {"openapi":"3.1.0","info":{"title":"Batch - REST API","version":"2.9"},"tags":[{"name":"Catalogs"}],"servers":[{"url":"https://api.batch.com/{version}","description":"production","variables":{"version":{"default":"2.12","description":"Version of the API"}}}],"security":[{"rest_key":[]}],"components":{"securitySchemes":{"rest_key":{"type":"http","scheme":"bearer","description":"## API Key Authentication\n\nAuthentication is required in order to interact with Batch's APIs.\n\nBatch implements authentication using API Keys, that we call the \"REST API Key\".\nYou can find it on your dashboard.\n\nPlease make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would\neasily be extractable.\n\n### How to authenticate\n\nIn order to authenticate your requests, add your REST API Key in the `Authorization` header and prefix it by `Bearer`. Example: `Authorization: Bearer bcd38d9rfb38ra28`.\n"}},"parameters":{"HeaderProjectKey":{"in":"header","name":"X-Batch-Project","description":"The unique project key, identifying a project on the Batch platform","schema":{"type":"string"},"required":true},"HeaderBatchBetaReplace":{"in":"header","name":"Batch-Beta","description":"Beta opt-in. This endpoint is in Beta. It accepts only requests that carry the `catalog-replace` flag. Batch rejects a request without the flag with a `400`.\n","schema":{"$ref":"#/components/schemas/BatchBetaFlags"},"required":true}},"schemas":{"BatchBetaFlags":{"description":"Value of the `Batch-Beta` header. It is a comma-separated list of Beta contract flags. Thus one request can opt into more than one Beta contract at the same time (`first-flag, second-flag`). Flags are lowercase and case-sensitive, and the order does not matter. Batch rejects an unknown flag with a `400` on any endpoint. When a contract becomes generally available, Batch continues to accept its flag but the flag has no more effect. Thus you never need to remove it.\n","type":"string"},"field":{"description":"A field defines a single attribute type that items in the catalog can have. Each field has a unique name and a type.","type":"object","required":["name","type"],"properties":{"name":{"type":"string","description":"The name of the field as it will appear on catalog items.","pattern":"[a-z0-9_]+$","minLength":1,"maxLength":250},"type":{"$ref":"#/components/schemas/field_type","description":"The data type for this field, such as integer or string."}}},"field_type":{"type":"string","description":"Enumerates the possible data types allowed for catalog fields.","enum":["array","bool","date","float","integer","string","url"]},"Error":{"type":"object","required":["error_message","error_code"],"properties":{"error_message":{"description":"A human readable error message","type":"string"},"error_code":{"description":"Error code","type":"string"}}}},"responses":{"400":{"description":"The request is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The Rest API Key is not valid for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Batch's services are under maintenance. Please try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"replaceStartConflict":{"description":"The replace session cannot be opened.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/catalogs/replace/start":{"post":{"operationId":"catalog_replace_start","summary":"Replace Start","description":"**Beta.** Catalog replace is a Beta feature and can change. Send the `Batch-Beta: catalog-replace` header on each call.\n

Opens a replace session on an existing catalog. A replace changes the entire contents of a catalog, and optionally its schema, in one atomic operation. Batch adds the new items to a hidden revision. The current revision continues to serve reads at the same time. Thus campaigns do not see an empty or a partly filled catalog.\n

Send the new items to `/catalogs/replace/items`. Then apply them with `/catalogs/replace/complete`, or discard them with `/catalogs/replace/cancel`. Each catalog can have only one open session at a time. The response gives a `replace_token`. Send this token in each subsequent call to identify the session.\n","tags":["Catalogs"],"parameters":[{"$ref":"#/components/parameters/HeaderProjectKey"},{"$ref":"#/components/parameters/HeaderBatchBetaReplace"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Identifier of the existing catalog to replace."},"fields":{"type":"array","description":"Schema of the new revision. If you do not send this field, the new revision keeps the schema of the current revision. If you send it, Batch validates it as for catalog creation. Thus a replace can also change the schema.\n","minItems":1,"items":{"$ref":"#/components/schemas/field"}}}}}}},"responses":{"202":{"description":"The replace session is open.","content":{"application/json":{"schema":{"type":"object","required":["replace_token"],"properties":{"replace_token":{"type":"string","description":"Token that identifies the replace session. Send it in each subsequent replace call."}}}}}},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"409":{"$ref":"#/components/responses/replaceStartConflict"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}}} ``` ### The replace flow A replace runs as a session of 3 calls: 1. **Start** (`/catalogs/replace/start`) opens the session and returns a `replace_token`. 2. **Add items** (`/catalogs/replace/items`) sends the new items to the pending revision. 3. **Complete** (`/catalogs/replace/complete`) applies the pending revision. To abandon a session instead, call **Cancel** (`/catalogs/replace/cancel`), which discards the pending revision. Each catalog can have only one open replace session at a time. #### Request structure **Route** The Catalog API has a POST endpoint that opens a replace session: `/catalogs/replace/start` **Headers and authentication** See Overview → Using Project APIs. This endpoint also needs the `Batch-Beta: catalog-replace` header. **Post data** The body of the request must contain a **valid JSON payload**. The payload gives the `name` of the catalog to replace. Add a `fields` array only if you also want to change the schema. If you do not send `fields`, the new revision keeps the current schema. If you send `fields`, Batch validates them as for catalog creation. To reuse the current schema: ```json { "name": "MOVIES" } ``` To replace with a new schema: ```json { "name": "MOVIES", "fields": [ { "name": "title", "type": "string" }, { "name": "price", "type": "float" } ] } ``` ### Responses #### Success If the call is successful, you receive an HTTP 202 confirmation and a replace\_token. Send this token in each subsequent replace call. The token identifies the session. ```json { "replace_token": "eqRqTF7xFznYoG0MLs1sIqM1JhmhGLTZ7I5NtM5f" } ``` ### Failure If a replace session is already open for this catalog, you receive an HTTP 409 with the `CATALOG_REPLACE_IN_PROGRESS` error code. For each other problem, you receive an error message that tells you what to do. Contact us at if you need more help. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://doc.batch.com/developer/api/cep/catalogs/replace-start.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.