Custom Lists

Custom lists let a policy match (or ignore) an explicit set of terms.

import ai.philterd.philter.model.CustomListSummary;
import ai.philterd.philter.model.CustomList;
import java.util.List;

// Create a list of terms. A name already in use is refused.
client.saveList("blocked-terms", "Terms to always redact", List.of("Acme", "Project X"));

// Replace the list's terms. A null description keeps the current one; "" clears it.
client.replaceList("blocked-terms", null, List.of("Acme", "Project X", "Project Y"));

// Retrieve a list's items and description.
CustomList list = client.getList("blocked-terms");
System.out.println(list.getItems() + " " + list.getDescription());

// A page of lists, with each one's name, description, and size but not its terms, and the total.
Page<CustomListSummary> lists = client.listCustomLists(null, new ListOptions().search("blocked"));
for (CustomListSummary summary : lists.getItems()) {
    System.out.println(summary.getName() + " (" + summary.getSize() + ")");
}

// Delete a list.
client.deleteList("blocked-terms");

saveList only creates. A name the owner already uses is refused with a ClientException whose getStatusCode() is 409 and getReason() is list_exists; replace the list with replaceList instead, which is refused with a 404 if there is no such list. A list holds up to 100 items of up to 50 characters each, and a description of up to 200 characters; more is an HTTP 400. getLimits().getCustomLists() reports these limits.

A list name is used in request paths, so it cannot contain /, \, ;, %, or a control character, and cannot be . or ... saveList with such a name gets an HTTP 400, raised as a ClientException whose getReason() is invalid_request. Since no list can have such a name, deleteList always names the list in the path.