Create a list version
Creates a draft version of a list with its own query, layout, and options. The list itself does not change until the version is applied. Returns the created version.
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_*).
The unique ID of the list.
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-10 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/string/versions" \ -H "clarify-version: 2026-10" \ -H "Content-Type: application/json" \ -d '{ "query": { "sql": "SELECT * FROM deal WHERE amount >= 50000" }, "layout": "table", "options": {} }'{ "data": { "type": "list-version", "id": "3b8f1d6a-5c2e-4a7b-9d0f-1e4c6a8b2d93", "attributes": { "_id": "3b8f1d6a-5c2e-4a7b-9d0f-1e4c6a8b2d93", "list_id": "9d2c4e6f-8a1b-4c3d-9e5f-7a9b1c3d5e7f", "query": { "sql": "SELECT * FROM deal WHERE amount >= 50000" }, "layout": "table", "options": {}, "_created_at": "2026-01-15T09:30:00.000Z", "_created_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81", "_updated_at": "2026-02-01T17:45:00.000Z", "_updated_by": "7d4e2f9a-1b3c-4d5e-8f6a-9c0b2d4e6f81" } }}Apply a list version
Copies the version’s query, layout, and options onto the list and records it as the applied version. Publishes the list too unless `publish` is `false`. Returns the updated list.
Get a list version
Returns a draft version of a list by ID as a JSON:API resource. A version holds a query, layout, and options that can later be applied to the list.