---
title: "Create a list."
method: POST
path: "/api/lists/{name}"
tags: ["Custom Lists"]
---

# Create a list.

`POST /api/lists/{name}`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/lists/{name}`
- Auth: HTTP bearer

Creates a list from the request body's items and optional description, which defaults to an empty string. A name the owner already uses is refused with 409; replace an existing list with PUT /api/lists/{name}. Requires the `lists:write` scope.

## Path parameters

- `name` string, required

## Query parameters

- `owner` string

## Headers

- `Authorization` string, required

## Request body

- CustomListRequest
  - `description` string: The list's description. On create, left out means an empty string. On replace, left out keeps the list's description, and an empty string clears it.
  - `items` string[], required: The list's items. Required, with at least one item that is not empty.

## Response `201`

The list was created.

- GenericResponse
  - `field` string: For a request refused as invalid, the parameter or body field that was invalid, when one is.
  - `message` string: What happened, written for a person to read. It may change; use reason in code.
  - `reason` string: For an error, why the request was refused, as a stable code a client can act on. The codes are listed in the API documentation under Errors.

## Other responses

- `400`: The list name is empty or cannot contain /, \, ;, %, or control characters, and cannot be . or .., the body is not a list with items, the list contains too many items (maximum 100), an item is too long (maximum 50 characters), the description is too long (maximum 200 characters), or the request has a description parameter.
- `401`: Unauthorized
- `403`: Insufficient scope, disabled API, or access denied.
- `404`: The owner does not exist, or the caller may not reach it. The API does not distinguish the two, so an owner value cannot be used to discover accounts.
- `406`: No representation matches Accept.
- `409`: The list was not created because the owner already has a list with this name; reason is list_exists. Nothing is changed.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-17** `25d87e0bb8f0`: 2 breaking, 1 warning, 1 info
  - added the new required request property `items`
  - the request's body type changed from `array` to `object`
  - deleted the `query` request parameter `description`
  - added the new optional request property `description`
- **2026-10-10** `c4f85daa9208`: 16 info
  - added the optional property `field` to the response with the `201` status
  - added the optional property `field` to the response with the `400` status
  - added the optional property `field` to the response with the `401` status
  - added the optional property `field` to the response with the `404` status
  - …12 more
- **2026-10-06** `7ea12b0eb331`: 1 info
  - removed the non-success response with the status `412`
- **2026-10-06** `a35e2c11efff`: 1 breaking, 1 info
  - removed the success response with the status `200`
  - added the non-success response with the status `409`
- **2026-10-06** `65fb75e47379`: 1 breaking
  - for the `query` request parameter `description`, default value `` was removed

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/lists/:name/post.md)

---

[API](https://skmtc.dev/philterd/apis/philter-api.md) - [All operations](https://skmtc.dev/philterd/apis/philter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/philterd/apis/philter-api/revisions/aa3d7ad1aab4?raw)