---
title: "Create a new Custom List Version"
method: POST
path: "/custom-lists/{customListToken}/versions"
tags: ["Custom Lists"]
---

# Create a new Custom List Version

`POST /custom-lists/{customListToken}/versions`

<dl> <dt> To create a new <b>major version</b> of a list: </dt> <dd>- Define or update columns and provide entries.</dd> <dt> To create a new <b>minor version</b> of a list: </dt> <dd>- Add entries to an existing version.</dd> <dd>- Delete entries from an existing version.</dd> <dd>- Modify entries in an existing version.</dd> <dd>- Replace all entries in an existing version.</dd> <dd>- Restore an existing version.</dd> </dl>

## Request body

- union
  - object
    - `columns` object[], required — Column definitions for the custom list. When updating the set of columns, a new major version will be created.
      - `name` string, required — Name of the column
      - `sort_order` integer — Sort order for the column (optional)
      - `contains_pii` boolean — Whether the column contains PII. Defaults to false if not provided.
    - `data` object[], required — Array of data entries to start the new major list version.
    - `notes` string — Optional notes about this version
    - `changelog` string — Optional changelog for this version
  - object
    - `base_version` object, required — Version to base new minor version on. Provide 'major_version' AND 'minor_version' to reference the existing version to add entries to. This will create a new minor version.
      - `major_version` integer, required
      - `minor_version` integer, required
    - `added` object[], required — Array of data entries to append to the list. Cannot be combined with 'deleted' or 'modified'.
    - `notes` string — Optional notes about this version
    - `changelog` string — Optional changelog for this version
  - object
    - `base_version` object, required — Version to base new minor version on. Provide 'major_version' AND 'minor_version' to reference the existing version to delete entries from. This will create a new minor version.
      - `major_version` integer, required
      - `minor_version` integer, required
    - `deleted` string[], required — Array of 'list_row_id' values identifying entries to remove from the list. Cannot be combined with 'added' or 'modified'. The base version must have a 'list_row_id' column, and all provided IDs must exist in the base version.
    - `notes` string — Optional notes about this version
    - `changelog` string — Optional changelog for this version
  - object
    - `base_version` object, required — Version to base new minor version on. Provide 'major_version' AND 'minor_version' to reference the existing version to modify entries in. This will create a new minor version.
      - `major_version` integer, required
      - `minor_version` integer, required
    - `modified` object[], required — Array of replacement entries. Each entry must include a 'list_row_id' matching an existing row in the base version; the entire row is replaced with the provided object. Cannot be combined with 'added' or 'deleted'. All provided 'list_row_id' values must exist in the base version.
      - `list_row_id` string, required — ID of the row to replace.
    - `notes` string — Optional notes about this version
    - `changelog` string — Optional changelog for this version
  - object
    - `base_version` object, required — Version to base new minor version on. Provide 'major_version' to reference the existing major version to replace all entries. This will create a new minor version.
      - `major_version` integer, required
      - `minor_version` integer
    - `data` object[], required — Array of data entries to replace all existing entries in the list version.
    - `notes` string — Optional notes about this version
    - `changelog` string — Optional changelog for this version
  - object
    - `base_version` object, required — Version to restore as new. Provide 'major_version' AND 'minor_version' to reference the existing version to restore as new. This will create a new minor version.
      - `major_version` integer, required
      - `minor_version` integer, required
    - `notes` string — Optional notes about this version

## Response `201`

Successfully created custom list version

- object
  - `custom_list_token` string
  - `version` string

## Other responses

- `400` — Bad request - Invalid Input Data
- `403` — Forbidden - Insufficient Permissions
- `404` — Custom List Not Found

---

[API](https://skmtc.dev/alloy/apis/alloy-api.md) · [All operations](https://skmtc.dev/alloy/apis/alloy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/alloy/alloy-api/revisions/405799de4d2a/schema)