Update a list

Applies a partial update to a list: only the fields present in the body are changed. The object’s default list cannot be updated. Returns the updated list.

Authorization

apiKey

Authorization<token>

API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.

In: header

Path Parameters

workspace*string

The workspace slug — the {slug} segment of your Clarify workspace URL.

object*string

The object type: a built-in entity (person, company, deal, …) or a custom object (c_*).

list*string

The unique ID of the list.

Query Parameters

silent?boolean

When true, suppresses in-app and Slack notifications for this mutation.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

title?string

The display name of the list.

emoji?string

The emoji shown next to the list, or null if unset.

description?string

A short description of the list.

layout?string

How the list is rendered in the app: table or board.

options?

View-level display options such as column widths and layout.

query?

For dynamic lists, the SQL query that defines membership; null for static and default lists.

rank?number

The sort position of the list relative to its siblings.

Response Body

`application/json`

curl -X PATCH "https://example.com/workspaces/string/objects/string/lists/string" \  -H "Content-Type: application/json" \  -d '{    "title": "Enterprise deals (FY26)"  }'

{
  "data": {
    "type": "list",
    "id": "9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f",
    "attributes": {
      "_id": "9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f",
      "user_id": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",
      "entity": "deal",
      "title": "Enterprise deals",
      "emoji": "🏢",
      "description": "Open deals with enterprise accounts.",
      "type": "dynamic",
      "state": "published",
      "layout": "table",
      "options": {},
      "query": {
        "sql": "SELECT * FROM deal WHERE amount >= 50000"
      },
      "owner_id": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",
      "rank": 0,
      "applied_version_id": null,
      "list_evaluation_status": "idle",
      "list_evaluation_started_at": null,
      "last_list_evaluation_at": "2026-02-01T17:45:00.000Z",
      "_updated_at": "2026-02-01T17:45:00.000Z",
      "_updated_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81",
      "_created_at": "2026-01-15T09:30:00.000Z",
      "_created_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81"
    }
  }
}