Clarify APIAPI Basics
Pagination
Paginate through large result sets
List endpoints return one page of results at a time, using offset-based
pagination. The default page size is 50 records. There's no hard maximum, but
we recommend keeping page[limit] at 1000 or below; larger pages take longer
to return.
Request
Control the page with the page[limit] and page[offset] parameters:
curl --globoff \
-H "Authorization: api-key YOUR_API_KEY" \
"https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page[limit]=100&page[offset]=200"| Parameter | Type | Default | Description |
|---|---|---|---|
page[limit] | integer | 50 | Records per page (recommended max 1000) |
page[offset] | integer | 0 | Number of records to skip before the current page |
Response
The response includes pagination metadata and navigation links:
{
"data": [...],
"meta": {
"total_records": 1250,
"total_pages": 13,
"offset": 200,
"limit": 100
},
"links": {
"next": "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page[limit]=100&page[offset]=300",
"prev": "https://api.clarify.ai/v1/workspaces/acme/objects/person/resources?page[limit]=100&page[offset]=100"
}
}Both links keys are always present. next is null on the last page, and
prev is null on the first page.
| Field | Description |
|---|---|
meta.total_records | Total matching records across all pages |
meta.total_pages | Total number of pages |
meta.offset | Offset of the current page |
meta.limit | Current page size |
links.next | URL for the next page, or null on the last page |
links.prev | URL for the previous page, or null on the first |
Fetching all pages
Follow the links.next URL until it's null:
async function fetchAll(workspace, object, apiKey) {
const records = [];
let url = `https://api.clarify.ai/v1/workspaces/${workspace}/objects/${object}/resources?page[limit]=100`;
while (url) {
const res = await fetch(url, {
headers: { Authorization: `api-key ${apiKey}` },
});
const json = await res.json();
records.push(...json.data);
url = json.links?.next;
}
return records;
}Ordering
Sort results with the sortOrder parameter:
curl --globoff \
-H "Authorization: api-key YOUR_API_KEY" \
"https://api.clarify.ai/v1/workspaces/acme/objects/deal/resources?sortOrder[column]=amount&sortOrder[dir]=DESC"| Parameter | Description |
|---|---|
sortOrder[column] | Field name to sort by |
sortOrder[dir] | ASC or DESC |
See Filtering for narrowing results before you page through them.