# Alerts

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) serves.

## Prerequisites

- An API key in `x-api-key`, or a browser session cookie
- `X-Organization-Id` naming the workspace to act in, unless the session already has an active one
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/alerts` | [Get where workspace alerts are posted](#get-where-workspace-alerts-are-posted) |
| `DELETE` | `/v1/api/alerts/slack` | [Stop posting alerts to Slack](#stop-posting-alerts-to-slack) |
| `PUT` | `/v1/api/alerts/slack` | [Choose the Slack channel and alert kinds](#choose-the-slack-channel-and-alert-kinds) |
| `GET` | `/v1/api/alerts/slack/channels` | [List Slack channels the bot can post alerts to](#list-slack-channels-the-bot-can-post-alerts-to) |
| `POST` | `/v1/api/alerts/slack/test` | [Send a test alert to the Slack channel](#send-a-test-alert-to-the-slack-channel) |
| `PUT` | `/v1/api/alerts/telegram` | [Choose which alerts the linked Telegram chats receive](#choose-which-alerts-the-linked-telegram-chats-receive) |
| `POST` | `/v1/api/alerts/telegram/test` | [Send a test alert to the linked Telegram chats](#send-a-test-alert-to-the-linked-telegram-chats) |

## Get where workspace alerts are posted

`GET /v1/api/alerts` · operation ID `getAlertSettings`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertSettings | Connected Slack workspaces (with any alert scopes they lack), the Slack route, the linked Telegram chats and their route. With chats linked and nothing saved, the Telegram route is the implied default: every kind, enabled. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Stop posting alerts to Slack

`DELETE /v1/api/alerts/slack` · operation ID `deleteSlackAlertRoute`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertRouteRemoved | `removed` is false when no Slack channel was chosen. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Choose the Slack channel and alert kinds

`PUT /v1/api/alerts/slack` · operation ID `saveSlackAlertRoute`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `SaveSlackAlertRoute` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `channelId` | string | **yes** |  |
| `enabled` | boolean | **yes** |  |
| `kinds` | `reply.interested` | `delivery.unknown` | `run.failed` | `request.pending` | `secrets.vault_unreachable` | `work.started` | `work.delivered` | `project.ready_for_approval` | `project.finished`[] | **yes** |  |
| `teamId` | string | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertRoute | The saved route. Saving resets its health to `ok`. |
| `400` | ValidationError | The body is malformed. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | That Slack workspace is not connected to this workspace (`code: not_connected`). |
| `409` | ApiError | The Slack install predates alerts or its token was revoked; reconnect Slack (`code: needs_reconnect`). |
| `422` | ApiError | The channel does not exist, or it is private and the bot is not in it. |

## List Slack channels the bot can post alerts to

`GET /v1/api/alerts/slack/channels` · operation ID `listSlackAlertChannels`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `teamId` | query | **yes** | string | The connected Slack workspace (`team_id`). |
| `query` | query | no | string | Only channels whose name contains this (a leading `#` is ignored). |
| `cursor` | query | no | string | `nextCursor` from the previous page. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | SlackChannelPage | Public channels, and the private channels the bot was invited into — Slack shows a bot no others. A public channel works without the bot being a member. |
| `400` | ValidationError | A parameter is unknown or malformed. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | That Slack workspace is not connected to this workspace (`code: not_connected`). |
| `409` | ApiError | The Slack install predates alerts or its token was revoked; reconnect Slack (`code: needs_reconnect`). |
| `502` | ApiError | Slack refused the lookup for another reason. |
| `503` | ApiError | Slack is rate limiting; retry after the `Retry-After` header. |

## Send a test alert to the Slack channel

`POST /v1/api/alerts/slack/test` · operation ID `testSlackAlertRoute`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertTestResult | Whether Slack accepted it. A refusal that proves the channel or token is gone marks the route broken, and `route` shows that. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | No Slack channel has been chosen. |

## Choose which alerts the linked Telegram chats receive

`PUT /v1/api/alerts/telegram` · operation ID `saveTelegramAlertRoute`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `SaveTelegramAlertRoute` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `enabled` | boolean | **yes** |  |
| `kinds` | `reply.interested` | `delivery.unknown` | `run.failed` | `request.pending` | `secrets.vault_unreachable` | `work.started` | `work.delivered` | `project.ready_for_approval` | `project.finished`[] | **yes** |  |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertRoute | The saved route. |
| `400` | ValidationError | The body is malformed. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | No Telegram chat is linked to this workspace. |

## Send a test alert to the linked Telegram chats

`POST /v1/api/alerts/telegram/test` · operation ID `testTelegramAlertRoute`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | AlertTestResult | Whether at least one linked chat accepted it. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is not a workspace owner or admin. |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | No Telegram chat is linked to this workspace. |

## If a request fails

These apply to every operation on this page.

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — no such resource **in this workspace**. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)