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

# Table Health API Reference

> REST API reference for table health checks and their email and Slack alert channels, so you can script alert setup across clusters.

Everything on the [Table Health Dashboard](https://docs.startree.ai/corecapabilities/observability/table-health-and-alerting.md) is backed by REST endpoints on the StarTree Cloud data-manager service. Use them to read health check results and to create, change, and test alert channels from a script, for example to apply the same alert setup to every cluster you run.

> [!NOTE]
>
> The dashboard and its alerts are turned on per environment. Slack channels need Slack delivery turned on as well. If an endpoint below returns `404`, or Slack isn't listed by `GET /destinations/supported-types`, contact StarTree support.

## Endpoints

All paths are relative to `https://<your-domain>/api/data/manager`, where `<your-domain>` is your Data Portal host. Run the same calls against each cluster's domain to configure several clusters.

| Method | Path | Purpose |
| - | - | - |
| `GET` | `/api/clusterHealth` | Latest health check results for the tables you can read |
| `GET` | `/api/clusterHealth/list` | Every check with its description |
| `POST` | `/api/clusterHealth/refresh` | Run the health checks now |
| `GET` | `/api/clusterHealth/schedule` | How often the health checks run |
| `GET` | `/api/v1/table-health-check-notifications/destinations/supported-types` | Channel types available on this cluster |
| `GET` | `/api/v1/table-health-check-notifications/destinations/access` | Whether you can manage every channel |
| `GET` | `/api/v1/table-health-check-notifications/destinations` | List channels |
| `POST` | `/api/v1/table-health-check-notifications/destinations` | Create a channel |
| `PUT` | `/api/v1/table-health-check-notifications/destinations/{id}` | Change a channel |
| `DELETE` | `/api/v1/table-health-check-notifications/destinations/{id}` | Remove a channel |
| `GET` | `/api/v1/table-health-check-notifications/destinations/{id}/subscriptions` | A channel's table and check rows |
| `POST` | `/api/v1/table-health-check-notifications/destinations/test` | Send a test message |

In the API, an alert channel is called a **destination**.

## Authentication and Headers

All requests require a valid StarTree Cloud Bearer token.

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer <token>` |
| `Content-Type` | For requests with a body | `application/json` |
| `workspace` | No | Workspace ID for the `/api/clusterHealth/list`, `/refresh` and `/schedule` permission check. When omitted, the default workspace is used. The destination endpoints ignore it. |

### Permissions

| To | You need |
| - | - |
| Read health results | [`GetTableConfigs`](https://docs.startree.ai/corecapabilities/security/actions) on the tables: `GET /api/clusterHealth` returns only tables you can read, and `403` if you can read none. `/list`, `/refresh` and `/schedule` need [`GetHealth`](https://docs.startree.ai/corecapabilities/security/actions) on the workspace. |
| Create, change, test or remove any channel, including every Slack channel | `ManageTableHealthNotifications` on the cluster |
| Manage your own email channel | No extra permission. Without `ManageTableHealthNotifications`, you see and change only the email channel for your own address, and can add only tables you can read to it. |

`GET /destinations/access` tells you which of these applies to the token you're using.

***

## Health check results

### GET /api/clusterHealth

Returns the latest result of every table-level check shown on the dashboard, for the tables you can read. Checks run every 20 minutes by default (see `GET /api/clusterHealth/schedule` below).

```bash theme={null}
curl "https://<your-domain>/api/data/manager/api/clusterHealth" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
{
  "runTimestamp": 1763640000000,
  "healthCheckResult": {
    "TABLE": {
      "orders_REALTIME": {
        "KAFKA_CHECK": {
          "pass": false,
          "canRemediate": true,
          "details": [
            {
              "topic": "orders",
              "pass": false,
              "flushThresholdMillis": 86400000,
              "retentionMillis": 172800000
            }
          ]
        },
        "TABLE_SEGMENTS_RELOAD_CHECK": { "pass": true, "canRemediate": true }
      },
      "analytics.clicks_OFFLINE": {
        "TABLE_SEGMENT_ASSIGNMENT_CHECK": { "pass": true, "canRemediate": false }
      }
    }
  }
}
```

| Field | Type | Description |
| - | - | - |
| `runTimestamp` | number | When the checks ran, in epoch milliseconds |
| `healthCheckResult.TABLE` | object | One entry per table. The key is `<table>_<TYPE>` for the default workspace and `<workspace>.<table>_<TYPE>` otherwise. |
| `…[table][checkKey].pass` | boolean | Whether the check passed |
| `…[table][checkKey].canRemediate` | boolean | Whether you have permission to run the check's fix on this table |

Each check also carries its own diagnostic fields, such as `details` for `KAFKA_CHECK` or `numServersNeedingReload` and `reasons` for `TABLE_SEGMENTS_RELOAD_CHECK`. The [health check reference](https://docs.startree.ai/corecapabilities/observability/health-checks.md) describes them. Free-text error fields are redacted.

The check keys shown by default are:

| Key | Dashboard name |
| - | - |
| `TABLE_SEGMENT_ASSIGNMENT_CHECK` | Segment Assignment |
| `TABLE_SEGMENTS_RELOAD_CHECK` | Segment Reload |
| `KAFKA_CHECK` | Kafka Retention |
| `HIGH_CARDINALITY_DICTIONARY_CHECK` | Dictionary Cardinality |

### GET /api/clusterHealth/list

Returns every check the cluster runs, with its description, as `{"<CHECK_KEY>": {"description": "..."}}`. This includes cluster- and instance-level checks that the dashboard doesn't show.

### POST /api/clusterHealth/refresh

Runs the health checks now. The new results appear in `GET /api/clusterHealth` after a minute or two. Calls are limited to one every 30 seconds.

```json theme={null}
{ "triggered": true, "lastRefreshedAtMs": 1763640000000 }
```

| Field | Type | Description |
| - | - | - |
| `triggered` | boolean | `false` when the call was ignored because a refresh ran in the last 30 seconds |
| `lastRefreshedAtMs` | number | When the last refresh was started, in epoch milliseconds |

### GET /api/clusterHealth/schedule

```json theme={null}
{ "enabled": true, "frequencyMinutes": 20 }
```

| Field | Type | Description |
| - | - | - |
| `enabled` | boolean | Whether the checks run on a schedule |
| `frequencyMinutes` | number \| null | Minutes between runs. `null` when the cluster uses the default (20 minutes) or the checks are off. |

***

## Alert channels (destinations)

A destination is one email address or one Slack incoming webhook, with its own coverage and schedule. Destinations are cluster-wide: one destination can cover tables in every workspace.

### GET /supported-types

`/api/v1/table-health-check-notifications/destinations/supported-types` returns the destination types you can create on this cluster: `["EMAIL"]`, or `["EMAIL", "SLACK"]` when Slack delivery is turned on.

### GET /access

`/api/v1/table-health-check-notifications/destinations/access` returns `{"canManageAllChannels": true}` when the caller has `ManageTableHealthNotifications` on the cluster, and `false` otherwise.

### GET /destinations

Lists destinations, ordered by `id`. Add `?type=EMAIL` or `?type=SLACK` to filter. Without `ManageTableHealthNotifications`, the list contains only your own email destination, if you have one.

```bash theme={null}
curl "https://<your-domain>/api/data/manager/api/v1/table-health-check-notifications/destinations?type=SLACK" \
  -H "Authorization: Bearer <token>"
```

```json theme={null}
[
  {
    "id": 13,
    "type": "SLACK",
    "target": "https://hooks.slack.com/services/T04…/B07…/****",
    "enabled": true,
    "coversAll": true,
    "immediateEnabled": true,
    "digestEnabled": false,
    "digestIntervalMinutes": 360,
    "reminderEnabled": true,
    "reminderCron": "0 15 11 * * *",
    "reminderTimeZone": "Asia/Kolkata",
    "nextReminderAt": 1763704500000,
    "createdBy": "admin@example.com",
    "createdAt": 1763640000000,
    "updatedBy": "admin@example.com",
    "updatedAt": 1763640000000
  }
]
```

### Destination object

| Field | Type | Description |
| - | - | - |
| `id` | number | Destination ID |
| `type` | string | `EMAIL` or `SLACK` |
| `target` | string | The email address, or the Slack webhook URL with its secret masked (for example `https://hooks.slack.com/services/T04…/B07…/****`). The full webhook is never returned. |
| `enabled` | boolean | The channel's **On** switch. A disabled channel gets nothing. |
| `coversAll` | boolean | `true`: every workspace, table and check, including tables created later. `false`: only what its [subscriptions](#subscriptions) list. |
| `immediateEnabled` | boolean | **Post as they happen**: a message when a check newly fails or recovers |
| `digestEnabled` | boolean | **Digest of failures and recoveries**: one message per interval, skipped when nothing changed |
| `digestIntervalMinutes` | number | Digest interval: `60`, `360`, `720` or `1440` |
| `reminderEnabled` | boolean | **Still-failing reminders** on the `reminderCron` schedule |
| `reminderCron` | string | Reminder schedule as a six-field cron expression (see [Reminder schedule](#reminder-schedule)) |
| `reminderTimeZone` | string | IANA time zone for `reminderCron`, such as `UTC` or `America/New_York` |
| `nextReminderAt` | number \| null | Next reminder in epoch milliseconds. `null` when reminders are off. |
| `createdBy`, `updatedBy` | string \| null | Who created and last changed the destination |
| `createdAt`, `updatedAt` | number | Epoch milliseconds |

### POST /destinations

Creates a destination and returns `201` with the [destination object](#destination-object).

#### Request Body

| Field | Type | Required | Default | Description |
| - | - | - | - | - |
| `type` | string | Yes | | `EMAIL` or `SLACK`. Can't be changed later. |
| `target` | string | Yes | | An email address, or a Slack incoming webhook URL starting with `https://hooks.slack.com/services/` (see [How to create a Slack incoming webhook](https://docs.startree.ai/corecapabilities/observability/slack-incoming-webhook.md)) |
| `enabled` | boolean | No | `true` | |
| `coversAll` | boolean | No | `true` | |
| `immediateEnabled` | boolean | No | `true` | At least one of `immediateEnabled`, `digestEnabled` and `reminderEnabled` must be `true`. |
| `digestEnabled` | boolean | No | `false` | |
| `digestIntervalMinutes` | number | No | `360` | `60`, `360`, `720` or `1440` |
| `reminderEnabled` | boolean | No | `false` | |
| `reminderCron` | string | No | `"0 0 9 * * MON"` | Validated even when reminders are off |
| `reminderTimeZone` | string | No | `"UTC"` | |
| `subscriptions` | array | When `coversAll` is `false` | `[]` | See [Subscriptions](#subscriptions). Up to 1000 entries. |

Only one destination can exist per address or webhook; a second one returns `409`.

#### Example: Slack channel for every table

```bash theme={null}
curl -X POST "https://<your-domain>/api/data/manager/api/v1/table-health-check-notifications/destinations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SLACK",
    "target": "https://hooks.slack.com/services/T0000/B0000/XXXXXXXX",
    "coversAll": true,
    "immediateEnabled": true,
    "reminderEnabled": true,
    "reminderCron": "0 15 11 * * *",
    "reminderTimeZone": "Asia/Kolkata"
  }'
```

#### Example: email for two tables

```bash theme={null}
curl -X POST "https://<your-domain>/api/data/manager/api/v1/table-health-check-notifications/destinations" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "EMAIL",
    "target": "oncall@example.com",
    "coversAll": false,
    "immediateEnabled": true,
    "digestEnabled": true,
    "digestIntervalMinutes": 1440,
    "subscriptions": [
      { "workspaceId": "default", "tableKey": "orders_REALTIME", "tableHealthCheckKey": "*", "notificationsEnabled": true, "notificationsMuted": false },
      { "workspaceId": "analytics", "tableKey": "clicks_OFFLINE", "tableHealthCheckKey": "KAFKA_CHECK", "notificationsEnabled": true, "notificationsMuted": false }
    ]
  }'
```

### PUT /destinations/\{id}

Changes a destination and returns the updated [destination object](#destination-object). The body has the same fields as `POST /destinations`; any field you leave out keeps its current value.

* To keep a Slack destination's webhook, leave `target` out or send back the masked value from `GET`.
* Sending `subscriptions` **replaces** all of the destination's rows. Leave it out to keep them.
* Changing `target` drops messages still queued for the old address or webhook.

To pause a channel without losing its settings:

```bash theme={null}
curl -X PUT "https://<your-domain>/api/data/manager/api/v1/table-health-check-notifications/destinations/13" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

### DELETE /destinations/\{id}

Removes the destination, its subscriptions, and any messages still queued for it. Returns `204` with no body.

### GET /destinations/\{id}/subscriptions

Returns the destination's [subscription](#subscriptions) rows. For a `coversAll` destination these are its overrides, often none.

### POST /destinations/test

Sends a test message right away and returns once it's delivered. Test a saved destination by ID, or test an address or webhook before saving it.

```bash theme={null}
curl -X POST "https://<your-domain>/api/data/manager/api/v1/table-health-check-notifications/destinations/test" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "id": 13 }'
```

| Field | Type | Required | Description |
| - | - | - | - |
| `id` | number | One of `id` or `type` | A saved destination. When set, `type` and `target` are ignored. |
| `type` | string | One of `id` or `type` | `EMAIL` or `SLACK`, to test without saving |
| `target` | string | With `type` | The address or webhook to test |

```json theme={null}
{ "delivered": true, "subject": "Test: table-health alerts are set up" }
```

If Slack or the mail provider rejects the message (for example, a revoked webhook or an archived Slack channel), the call returns `400`. A temporary delivery failure returns `503`; retry it.

***

## Subscriptions

When `coversAll` is `false`, a destination gets alerts only for what its subscription rows cover. When `coversAll` is `true`, rows act as exceptions to full coverage, such as opting one table out or muting one check.

| Field | Type | Description |
| - | - | - |
| `workspaceId` | string | Workspace ID. Use `default` for the default workspace. `*` isn't allowed. |
| `tableKey` | string | Table name with its type suffix, such as `orders_REALTIME`, without the workspace prefix. `*` for every table in the workspace, including tables created later. |
| `tableHealthCheckKey` | string | A check key (see [Health check results](#health-check-results)), or `*` for every check |
| `notificationsEnabled` | boolean | `true` to get alerts for this scope, `false` to opt out of it |
| `notificationsMuted` | boolean | `true` to stop alerts for a failing check until it next passes |

For each table and check, the most specific matching row wins: an exact table and check, then `(table, *)`, then `(*, check)`, then `(*, *)`, then the destination's `coversAll`. For example, this `coversAll` destination gets every table except `staging_events_REALTIME`:

```json theme={null}
{
  "coversAll": true,
  "subscriptions": [
    { "workspaceId": "default", "tableKey": "staging_events_REALTIME", "tableHealthCheckKey": "*", "notificationsEnabled": false, "notificationsMuted": false }
  ]
}
```

A mute on an exact table and check sends the recovery message when the check passes, then clears itself. A mute on a wildcard row stays until you remove it.

An email destination gets alerts only for tables its recipient can read. A Slack destination gets every table it covers, so anyone in that Slack channel can see those table names.

## Reminder schedule

`reminderCron` uses six fields: second, minute, hour, day of month, month, day of week. It's evaluated in `reminderTimeZone` and can fire at most once an hour.

| Schedule | `reminderCron` |
| - | - |
| Every day at 09:00 | `0 0 9 * * *` |
| Weekdays at 11:15 | `0 15 11 * * MON-FRI` |
| Every 6 hours | `0 0 */6 * * *` |
| Mondays at 09:00 (default) | `0 0 9 * * MON` |

***

## Error Response

Errors return a JSON body with a human-readable `message` and the HTTP status. Some environments also return a `dpeCode` (for example `DPE-5241`) and `remediation` steps; see [Error codes](https://docs.startree.ai/corecapabilities/observability/error-codes.md).

| Status | When |
| - | - |
| `200` | Success (`201` for a new destination, `204` for a removed one) |
| `400` | Invalid request: a bad email address or webhook URL, no alert option turned on, an invalid `digestIntervalMinutes`, `reminderCron` or `reminderTimeZone`, incomplete subscription rows, more than 1000 rows, an attempt to change `type`, or a test message the provider rejected |
| `401` | Missing or invalid authentication token |
| `403` | You don't have the [permission](#permissions) the call needs, for example creating a Slack destination without `ManageTableHealthNotifications`, or subscribing to a table you can't read |
| `404` | The destination ID doesn't exist |
| `409` | A destination for that address or webhook already exists, or the destination type isn't turned on for this cluster (for example Slack, or email delivery for a test) |
| `503` | Health results or a test message are temporarily unavailable; retry |

***

## Example: set up the same alerts on several clusters

```bash theme={null}
#!/usr/bin/env bash
# Creates the same Slack alert channel on every cluster listed in clusters.txt.
# clusters.txt has one "<domain> <token>" pair per line.
set -euo pipefail

while read -r domain token; do
  curl -sf -X POST "https://${domain}/api/data/manager/api/v1/table-health-check-notifications/destinations" \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/json" \
    -d "{
      \"type\": \"SLACK\",
      \"target\": \"${SLACK_WEBHOOK_URL}\",
      \"coversAll\": true,
      \"immediateEnabled\": true,
      \"reminderEnabled\": true,
      \"reminderCron\": \"0 0 9 * * MON-FRI\",
      \"reminderTimeZone\": \"UTC\"
    }" && echo " -> ${domain}"
done < clusters.txt
```

Each cluster keeps its own destinations, so run the script once per cluster you add. A rerun returns `409` for clusters that already have the webhook; use `PUT /destinations/{id}` to change those.

***

## Related Documentation

> [card] [Table Health Dashboard & Alerting](https://docs.startree.ai/corecapabilities/observability/table-health-and-alerting.md)
>
> The dashboard, each check's fix, and how alerts behave.

> [card] [Health checks](https://docs.startree.ai/corecapabilities/observability/health-checks.md)
>
> Every check, its diagnostic fields, and what to do about a failure.

> [card] [Slack incoming webhook](https://docs.startree.ai/corecapabilities/observability/slack-incoming-webhook.md)
>
> Create the webhook URL a Slack destination needs.

> [card] [RBAC Actions](https://docs.startree.ai/corecapabilities/security/actions.md)
>
> The permission actions referenced on this page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.