Create a list
Creates a list on the given object type. A dynamic list derives its membership from the SQL query; a static list starts empty. Returns the created list.
API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.
In: header
Path Parameters
The workspace slug — the {slug} segment of your Clarify workspace URL.
The object type: a built-in entity (person, company, deal, …) or a custom object (c_*).
Query Parameters
When true, suppresses in-app and Slack notifications for this mutation and batches its live updates, so open views can lag by up to 20 seconds.
Header Parameters
The API version for this request. Send 2026-01 to get the behavior documented here. Omit it to use your API key's version, which this header can raise but not lower.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
curl -X POST "https://example.com/workspaces/string/objects/string/lists" \ -H "clarify-version: 2026-01" \ -H "Content-Type: application/json" \ -d '{ "title": "Enterprise deals", "emoji": "🏢", "description": "Open deals with enterprise accounts.", "layout": "table", "type": "dynamic", "query": { "sql": "SELECT * FROM deal WHERE amount >= 50000" } }'{ "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" } }}Export a list’s rows as CSV
Streams the rows of a list as a `text/csv` file download. The first row is a header of field names. Pass a `sql` statement in the body to export a custom query instead of the list’s own rows.
Delete a list
Permanently deletes a list. The object’s default list and the last remaining list on an object cannot be deleted. This cannot be undone.