---
title: "Replace one redact list."
method: PUT
path: "/api/redact-lists/{list}"
tags: ["Always/Never Redact Lists"]
---

# Replace one redact list.

`PUT /api/redact-lists/{list}`

## Request

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

Replaces one list, always or never, in full with the terms in the body, leaving the other list as it is, and moves it to its next revision. Send the revision you read in If-Match, quoted as the ETag gives it, so the write is refused with 409 and reason redact_list_changed if someone changed the list since; without If-Match the list is replaced whatever its revision. Terms are trimmed and blank entries are dropped. The list may contain up to 1000 terms, and each term may be up to 100 characters. Admins may replace another user's list by passing that user's username as owner. Requires the `lists:write` scope.

## Path parameters

- `list` string, required

## Query parameters

- `owner` string

## Headers

- `Authorization` string, required
- `If-Match` string

## Request body

- RedactListRequest
  - `terms` string[]: The list's complete contents. An empty array or an omitted field clears the list.

## Response `200`

The list was replaced. The body and the ETag header give its new revision.

- RedactListResponse
  - `revision` integer: The list's revision, which every write of the list increments. Send it back in If-Match when replacing the list so the write is refused if someone changed the list since. A list never written is at 0. The ETag header carries the same value.
  - `terms` string[]: The list's terms. A list with no saved terms is an empty array.

## Other responses

- `400`: The request body is malformed, the list has too many terms, a term is too long, or If-Match is not a revision.
- `401`: The Authorization header is absent or the API key is not recognized.
- `403`: Insufficient scope, disabled API, or access denied.
- `404`: The list is not always or never, or 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 is no longer at the revision given in If-Match. Nothing was written. Read the list again and retry.
- `413`: Content Too Large
- `415`: Unsupported Media Type
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-10** `c4f85daa9208`: 14 info
  - 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
  - added the optional property `field` to the response with the `413` status
  - …10 more
- **2026-10-10** `56b4fb403d21`: 1 info
  - endpoint added

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