---
title: "Update a list"
method: PATCH
path: "/v2/lists/{id}"
tags: ["Lists"]
---

# Update a list

`PATCH /v2/lists/{id}`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/lists/{id}`
- Auth: HTTP bearer

Update a list's metadata. Use this to rename a list, change its description, toggle notifications_enabled (opt the list into the daily new-search-results email), or publish/unpublish it via is_public. Provide at least one of: title, description, notifications_enabled, or is_public. The list type cannot be changed after creation. Returns the updated list with new timestamps.

## Path parameters

- `id` string, required: List ID

## Request body

- UpdateListRequest: Request body for updating list metadata
  - `title` string: New list title
  - `description` string, nullable: New list description (null to clear)
  - `notifications_enabled` boolean: Opt the list into the daily "new search results" email sweep (off by default)
  - `is_public` boolean: Publish the list, or unpublish it. A published list is readable by anyone holding its public identifier — names, titles, companies and screening scores, never contact details or introduction paths. Publishing mints that identifier the first time and returns it as `slug`; unpublishing keeps it, so republishing later restores the same URL.

## Response `200`

List updated successfully

- object
  - `data` UpdateListResponse, required: Response after updating a list
    - `id` number, required: Unique list identifier
    - `title` string, required: List title
    - `type` 'people' | 'company', required: Type of entities in the list
    - `description` string, nullable, required: List description
    - `item_count` number, required: Number of items in the list
    - `notifications_enabled` boolean, required: Whether the list is opted into the daily "new search results" email sweep
    - `is_public` boolean, required: Whether anyone holding the public identifier can read this list.
    - `public_id` string, nullable, required: Public identifier, minted the first time the list is published. Null until then.
    - `results_diff_since_last_run` number, nullable, required: New items appended by the most recent completed fill run (creation fill, manual refresh, or nightly re-run). Null until a run records one.
    - `created_at` string, required: ISO 8601 creation timestamp
    - `updated_at` string, required: ISO 8601 last update timestamp
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `404`: List not found

---

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