---
title: "Create New List"
method: POST
path: "/lists"
tags: ["lists"]
---

# Create New List

`POST /lists`

Create New List.
If the list already exists "Conflict" will be returned.
The provided populated data may be provided unsorted, but should not contain duplicate element IDs.

Required security scopes:
  * `api:manage`

## Query parameters

- `replace` boolean

## Request body

- RankList
  - `id` string, required — The ID of the list to apply the operation on. Can be `a` to `z` (both upper/lower case), `0` to `9` or one of these characters `_-.`
  - `load_index` boolean — Load Index on server startup
  - `merge_size` integer — Merge adjacent Segments with less than this number of entries
  - `metadata` object — Custom metadata. String to String hash.
  - `populate` Element[] — Populate list with specified elements
    - `id` integer, required — ID of element
    - `payload` object — Custom payload. Stored untouched. On updates null means do not update. `{}` is the empty value.
    - `score` integer, required — Score of the element. Higher score gives higher placement.
    - `tie_breaker` integer — Tie breaker, used if score matches for consistent sorting. Higher value = higher placement if score is equal.
  - `set` string, required — Set used for storage
  - `split_size` integer — Split Segments larger than this number of entries

## Response `200`

OK

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `409` — Conflict

---

[API](https://skmtc.net/vivino/apis/the-rankdb-api.md) · [All operations](https://skmtc.net/vivino/apis/the-rankdb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vivino/the-rankdb-api/versions/7a45b5309a11/schema)