> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickbase.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Segments

> Manage the saved filter segments on one of the current team's sites.

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](/api/conventions#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](/api/conventions) for the base URL, headers, and error conventions shared by every endpoint.

### List segments

```http theme={null}
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`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl "https://clickbase.so/api/sites/example.com/segments" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

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

  ```python title="Python" theme={null}
  requests.get('https://clickbase.so/api/sites/example.com/segments', headers={'Authorization': f'Bearer {token}', 'Accept':'application/json'})
  ```
</CodeGroup>

### Create a segment

```http theme={null}
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](/api/conventions#filters). |

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

<CodeGroup>
  ```bash title="curl" theme={null}
  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"}}'
  ```

  ```javascript title="JavaScript" theme={null}
  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' } }),
  })
  ```

  ```python title="Python" theme={null}
  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'}},
  )
  ```
</CodeGroup>

### Update a segment

```http theme={null}
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`.

<CodeGroup>
  ```bash title="curl" theme={null}
  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"}}'
  ```

  ```javascript title="JavaScript" theme={null}
  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' } }),
  })
  ```

  ```python title="Python" theme={null}
  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'}},
  )
  ```
</CodeGroup>

### Delete a segment

```http theme={null}
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`.

<CodeGroup>
  ```bash title="curl" theme={null}
  curl -X DELETE "https://clickbase.so/api/sites/example.com/segments/{segment}" \
    -H "Authorization: Bearer {token}" \
    -H "Accept: application/json"
  ```

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

  ```python title="Python" theme={null}
  requests.delete(
      f'https://clickbase.so/api/sites/example.com/segments/{segment_id}',
      headers={'Authorization': f'Bearer {token}', 'Accept': 'application/json'},
  )
  ```
</CodeGroup>