REST API

Segments

Manage the saved filter segments on one of the current team's sites. A segment is a named snapshot of dashboard filters (name + filters) any workspace member can create, apply, update, or delete. Filters are the same allowlisted keys as reporting endpoints (see Filters); they are normalized through ResolveFilters on write, so unknown keys are dropped and visit_count must use an operator prefix (is:1 / gte:2 / lte:5). A site is addressed by {siteKey} (UUID or domain). All endpoints require Authorization: Bearer {token}. See Conventions for the base URL, headers, and error conventions shared by every endpoint.

List segments

GET /api/sites/{siteKey}/segments

List a site's saved segments, ordered by name.

Path parameters

Parameter	Type	Required	Description
`siteKey`	string	Yes	Site UUID or domain.

Response — flat JSON array of:

Field	Type	Description
`id`	string (uuid)	Segment id.
`name`	string	Display name (unique per site).
`filters`	object	Normalized filter map (string or string[] values).
`created_at`	string (ISO 8601) \| null	When the segment was created.
`updated_at`	string (ISO 8601) \| null	When the segment was last edited.

Status: 200 OK.

curl "https://clickbase.so/api/sites/example.com/segments" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch('https://clickbase.so/api/sites/example.com/segments', { headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' } })

requests.get('https://clickbase.so/api/sites/example.com/segments', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})

Create a segment

POST /api/sites/{siteKey}/segments

Save the current filter stack as a named segment. At least one allowlisted filter must remain after normalization, otherwise the request returns 422.

Body parameters

Parameter	Type	Required	Description
`name`	string	Yes	Display name. Max 120 chars. Must be unique on this site.
`filters`	object	Yes	Filter map using the same keys as Filters.

Response — the created segment (same fields as the list). Status: 201 Created.

curl -X POST "https://clickbase.so/api/sites/example.com/segments" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name": "First-time US", "filters": {"visit_count": "is:1", "country": "US"}}'

await fetch('https://clickbase.so/api/sites/example.com/segments', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ name: 'First-time US', filters: { visit_count: 'is:1', country: 'US' } }),
})

requests.post(
    'https://clickbase.so/api/sites/example.com/segments',
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
    json={'name': 'First-time US', 'filters': {'visit_count': 'is:1', 'country': 'US'}},
)

Update a segment

PATCH /api/sites/{siteKey}/segments/{segment}

Rename a segment and/or replace its filters. Either field may be omitted; when filters is sent it must still contain at least one allowlisted key after normalization. A foreign/unknown segment id (not on this site) returns 404 Not Found.

Path parameters

Parameter	Type	Required	Description
`siteKey`	string	Yes	Site UUID or domain.
`segment`	string	Yes	Segment id. A foreign/unknown id returns `404`.

Body parameters

Parameter	Type	Required	Description
`name`	string	No	New display name. Max 120 chars. Unique on this site.
`filters`	object	No	Replacement filter map (same allowlist as create).

Response — the updated segment. Status: 200 OK.

curl -X PATCH "https://clickbase.so/api/sites/example.com/segments/{segment}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name": "Returning US", "filters": {"visit_count": "gte:2", "country": "US"}}'

await fetch(`https://clickbase.so/api/sites/example.com/segments/${segmentId}`, {
  method: 'PATCH',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
  body: JSON.stringify({ name: 'Returning US', filters: { visit_count: 'gte:2', country: 'US' } }),
})

requests.patch(
    f'https://clickbase.so/api/sites/example.com/segments/{segment_id}',
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
    json={'name': 'Returning US', 'filters': {'visit_count': 'gte:2', 'country': 'US'}},
)

Delete a segment

DELETE /api/sites/{siteKey}/segments/{segment}

Remove a saved segment. Cannot be undone. A foreign/unknown segment id returns 404 Not Found.

Path parameters

Parameter	Type	Required	Description
`siteKey`	string	Yes	Site UUID or domain.
`segment`	string	Yes	Segment id. A foreign/unknown id returns `404`.

Status: 204 No Content.

curl -X DELETE "https://clickbase.so/api/sites/example.com/segments/{segment}" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

await fetch(`https://clickbase.so/api/sites/example.com/segments/${segmentId}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
})

requests.delete(
    f'https://clickbase.so/api/sites/example.com/segments/{segment_id}',
    headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
)