---
title: "Replace Start"
method: POST
path: "/catalogs/replace/start"
tags: ["Catalogs"]
---

# Replace Start

`POST /catalogs/replace/start`

**Beta.** Catalog replace is a Beta feature and can change. Send the `Batch-Beta: catalog-replace` header on each call.
<br/><br/>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.
<br/><br/>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.

## Headers

- `X-Batch-Project` string, required
- `Batch-Beta` string, required — 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.

## Request body

- object
  - `name` string, required — Identifier of the existing catalog to replace.
  - `fields` Field[] — 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.
    - `name` string, required — The name of the field as it will appear on catalog items.
    - `type` 'array' | 'bool' | 'date' | 'float' | 'integer' | 'string' | 'url', required — Enumerates the possible data types allowed for catalog fields.

## Response `202`

The replace session is open.

- object
  - `replace_token` string, required — Token that identifies the replace session. Send it in each subsequent replace call.

## Other responses

- `400` — The request is malformed
- `401` — The Rest API Key is not valid for this project
- `404` — Not found
- `409` — The replace session cannot be opened.
- `429` — Too Many Requests
- `500` — Unexpected error
- `503` — Batch's services are under maintenance. Please try again later

---

[API](https://skmtc.net/batch/apis/batch-rest-api.md) · [All operations](https://skmtc.net/batch/apis/batch-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/batch/batch-rest-api/revisions/ec696334ff35/schema)