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

# Replace a list.

`PUT /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

Replaces the items of an existing list with the request body's items. description is optional: left out, the list keeps its description; given as an empty string, it is cleared. 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 `200`

The list was replaced.

- 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 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`: There is no such list, or the owner does not exist or the caller may not reach it.
- `406`: No representation matches Accept.
- `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 `200` 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** `a35e2c11efff`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/philterd/apis/philter-api/changes/api/lists/:name/put.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)