> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getarca.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Update list

> Updates one or more properties of a list. Only the fields you include are changed.

<Info>Requires the `lists:write` scope. Viewers cannot edit lists.</Info>

## Path parameters

<ParamField path="id" type="string" required>
  The numeric list ID.
</ParamField>

## Request body

All fields are optional. Send only the fields you want to update.

<ParamField body="name" type="string">
  New list name.
</ParamField>

<ParamField body="icon" type="string">
  Icon identifier slug.
</ParamField>

<ParamField body="color" type="string">
  List color.
</ParamField>

<ParamField body="folder_id" type="string">
  Move the list to a different folder by passing a new folder ID.
</ParamField>

## Response

Returns the full updated list object.

<ResponseField name="id" type="number" required>
  List identifier.
</ResponseField>

<ResponseField name="workspace_id" type="number" required>
  Workspace this list belongs to.
</ResponseField>

<ResponseField name="folder_id" type="number | null">
  Parent folder ID. `null` if not inside a folder.
</ResponseField>

<ResponseField name="name" type="string" required>
  List name.
</ResponseField>

<ResponseField name="icon" type="string | null">
  Icon.
</ResponseField>

<ResponseField name="color" type="string | null">
  Color.
</ResponseField>

<ResponseField name="position" type="number" required>
  Sort position (unchanged by this endpoint).
</ResponseField>

<ResponseField name="created_at" type="string" required>
  UTC ISO-8601 creation timestamp.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": 25,
    "workspace_id": 3,
    "folder_id": 10,
    "name": "API Integration Tasks",
    "icon": "folder-1",
    "color": "green",
    "position": 3,
    "created_at": "2026-03-18T11:00:00.000Z"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Scope 'lists:write' is required for this endpoint"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "List not found"
  }
  ```
</ResponseExample>