Update a task list

PATCH /v1/lists/{listId}

Updates attributes of an existing task list. Only fields you provide are changed. The API key’s owner must be a member of the list.

To change the archived state, use the dedicated Archive a task list and Unarchive a task list endpoints.

Connected web clients in the team receive a realtime tasklists refetch event so the change appears immediately in their sidebar.

Request

Path parameters

Name	Type	Required	Description
listId	string	yes	Numeric ID of the list.

Body

Content-Type: application/json

Field	Type	Required	Description
name	string	no	New display name. Must contain at least one non-whitespace character.
color	string	no	New color tag. See valid values below.

Valid color values: Gray, Red, Orange, Yellow, Amber, Lime, Green, Teal, Sky, Blue, Purple, Pink.

Example request

{
  "name": "Q3 launch — frozen scope",
  "color": "Amber"
}

Response

200 OK — the updated list:

Field	Type	Description
id	number	Numeric ID of the list.
name	string	Display name after the update.
color	string	Color tag after the update.
isArchived	boolean	Archived state (unchanged by this endpoint).

Example response

{
  "id": 27,
  "name": "Q3 launch — frozen scope",
  "color": "Amber",
  "isArchived": false
}

Errors

Status	Body	When
400	{ "error": "..." }	listId is not numeric, name is empty, or color is invalid.
403	{ "error": "You do not have access to this list." }	The API key’s owner is not a member of the list.
404	{ "error": "List <id> not found." }	No list with that ID exists in the bound team.