Hlix Alerts API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Alerts API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: Alerts
paths:
  /v1/api/alerts:
    get:
      operationId: getAlertSettings
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertSettings'
          description: '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':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Get where workspace alerts are posted
      tags:
      - Alerts
  /v1/api/alerts/slack:
    delete:
      operationId: deleteSlackAlertRoute
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRouteRemoved'
          description: '`removed` is false when no Slack channel was chosen.'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Stop posting alerts to Slack
      tags:
      - Alerts
    put:
      operationId: saveSlackAlertRoute
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveSlackAlertRoute'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRoute'
          description: The saved route. Saving resets its health to `ok`.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: The body is malformed.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'That Slack workspace is not connected to this workspace (`code: not_connected`).'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'The Slack install predates alerts or its token was revoked; reconnect Slack (`code: needs_reconnect`).'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The channel does not exist, or it is private and the bot is not in it.
      summary: Choose the Slack channel and alert kinds
      tags:
      - Alerts
  /v1/api/alerts/slack/channels:
    get:
      operationId: listSlackAlertChannels
      parameters:
      - description: The connected Slack workspace (`team_id`).
        in: query
        name: teamId
        required: true
        schema:
          type: string
      - description: Only channels whose name contains this (a leading `#` is ignored).
        in: query
        name: query
        required: false
        schema:
          type: string
      - description: '`nextCursor` from the previous page.'
        in: query
        name: cursor
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelPage'
          description: Public channels and private channels to which the Slack bot was invited. The bot can post to a public channel without joining it.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: A parameter is unknown or malformed.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'That Slack workspace is not connected to this workspace (`code: not_connected`).'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: 'The Slack install predates alerts or its token was revoked; reconnect Slack (`code: needs_reconnect`).'
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Slack refused the lookup for another reason.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: Slack is rate limiting; retry after the `Retry-After` header.
      summary: List Slack channels the bot can post alerts to
      tags:
      - Alerts
  /v1/api/alerts/slack/test:
    post:
      operationId: testSlackAlertRoute
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertTestResult'
          description: Whether Slack accepted it. A refusal that proves the channel or token is gone marks the route broken, and `route` shows that.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No Slack channel has been chosen.
      summary: Send a test alert to the Slack channel
      tags:
      - Alerts
  /v1/api/alerts/telegram:
    put:
      operationId: saveTelegramAlertRoute
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveTelegramAlertRoute'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertRoute'
          description: The saved route.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
          description: The body is malformed.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No Telegram chat is linked to this workspace.
      summary: Choose which alerts the linked Telegram chats receive
      tags:
      - Alerts
  /v1/api/alerts/telegram/test:
    post:
      operationId: testTelegramAlertRoute
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertTestResult'
          description: Whether at least one linked chat accepted it.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is not a workspace owner or admin.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No Telegram chat is linked to this workspace.
      summary: Send a test alert to the linked Telegram chats
      tags:
      - Alerts
components:
  schemas:
    SaveSlackAlertRoute:
      additionalProperties: false
      properties:
        channelId:
          pattern: ^[A-Z0-9]{2,32}$
          type: string
        enabled:
          type: boolean
        kinds:
          items:
            enum:
            - reply.interested
            - delivery.unknown
            - run.failed
            - request.pending
            - secrets.vault_unreachable
            - work.started
            - work.delivered
            - project.ready_for_approval
            - project.finished
            type: string
          maxItems: 9
          type: array
        teamId:
          pattern: ^[A-Z0-9]{2,32}$
          type: string
      required:
      - teamId
      - channelId
      - kinds
      - enabled
      type: object
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    AlertSettings:
      properties:
        slack:
          properties:
            route:
              anyOf:
              - properties:
                  enabled:
                    type: boolean
                  health:
                    enum:
                    - ok
                    - needs_reconnect
                    - channel_missing
                    type: string
                  kinds:
                    items:
                      enum:
                      - reply.interested
                      - delivery.unknown
                      - run.failed
                      - request.pending
                      - secrets.vault_unreachable
                      - work.started
                      - work.delivered
                      - project.ready_for_approval
                      - project.finished
                      type: string
                    type: array
                  lastError:
                    type:
                    - string
                    - 'null'
                  lastErrorAt:
                    type:
                    - string
                    - 'null'
                  provider:
                    enum:
                    - slack
                    - telegram
                    type: string
                  slackChannelId:
                    type:
                    - string
                    - 'null'
                  slackChannelName:
                    type:
                    - string
                    - 'null'
                  slackChannelPrivate:
                    type: boolean
                  slackTeamId:
                    type:
                    - string
                    - 'null'
                  updatedAt:
                    type:
                    - string
                    - 'null'
                required:
                - provider
                - slackTeamId
                - slackChannelId
                - slackChannelName
                - slackChannelPrivate
                - kinds
                - enabled
                - health
                - lastError
                - lastErrorAt
                - updatedAt
                type: object
              - type: 'null'
            workspaces:
              items:
                properties:
                  missingScopes:
                    items:
                      type: string
                    type: array
                  teamId:
                    type: string
                  teamName:
                    type: string
                required:
                - teamId
                - teamName
                - missingScopes
                type: object
              type: array
          required:
          - workspaces
          - route
          type: object
        telegram:
          properties:
            chats:
              items:
                properties:
                  chatId:
                    type: string
                  name:
                    type: string
                required:
                - chatId
                - name
                type: object
              type: array
            route:
              anyOf:
              - properties:
                  enabled:
                    type: boolean
                  health:
                    enum:
                    - ok
                    - needs_reconnect
                    - channel_missing
                    type: string
                  kinds:
                    items:
                      enum:
                      - reply.interested
                      - delivery.unknown
                      - run.failed
                      - request.pending
                      - secrets.vault_unreachable
                      - work.started
                      - work.delivered
                      - project.ready_for_approval
                      - project.finished
                      type: string
                    type: array
                  lastError:
                    type:
                    - string
                    - 'null'
                  lastErrorAt:
                    type:
                    - string
                    - 'null'
                  provider:
                    enum:
                    - slack
                    - telegram
                    type: string
                  slackChannelId:
                    type:
                    - string
                    - 'null'
                  slackChannelName:
                    type:
                    - string
                    - 'null'
                  slackChannelPrivate:
                    type: boolean
                  slackTeamId:
                    type:
                    - string
                    - 'null'
                  updatedAt:
                    type:
                    - string
                    - 'null'
                required:
                - provider
                - slackTeamId
                - slackChannelId
                - slackChannelName
                - slackChannelPrivate
                - kinds
                - enabled
                - health
                - lastError
                - lastErrorAt
                - updatedAt
                type: object
              - type: 'null'
          required:
          - chats
          - route
          type: object
      required:
      - slack
      - telegram
      type: object
    SaveTelegramAlertRoute:
      additionalProperties: false
      properties:
        enabled:
          type: boolean
        kinds:
          items:
            enum:
            - reply.interested
            - delivery.unknown
            - run.failed
            - request.pending
            - secrets.vault_unreachable
            - work.started
            - work.delivered
            - project.ready_for_approval
            - project.finished
            type: string
          maxItems: 9
          type: array
      required:
      - kinds
      - enabled
      type: object
    AlertTestResult:
      properties:
        delivered:
          type: boolean
        error:
          type:
          - string
          - 'null'
        route:
          anyOf:
          - properties:
              enabled:
                type: boolean
              health:
                enum:
                - ok
                - needs_reconnect
                - channel_missing
                type: string
              kinds:
                items:
                  enum:
                  - reply.interested
                  - delivery.unknown
                  - run.failed
                  - request.pending
                  - secrets.vault_unreachable
                  - work.started
                  - work.delivered
                  - project.ready_for_approval
                  - project.finished
                  type: string
                type: array
              lastError:
                type:
                - string
                - 'null'
              lastErrorAt:
                type:
                - string
                - 'null'
              provider:
                enum:
                - slack
                - telegram
                type: string
              slackChannelId:
                type:
                - string
                - 'null'
              slackChannelName:
                type:
                - string
                - 'null'
              slackChannelPrivate:
                type: boolean
              slackTeamId:
                type:
                - string
                - 'null'
              updatedAt:
                type:
                - string
                - 'null'
            required:
            - provider
            - slackTeamId
            - slackChannelId
            - slackChannelName
            - slackChannelPrivate
            - kinds
            - enabled
            - health
            - lastError
            - lastErrorAt
            - updatedAt
            type: object
          - type: 'null'
      required:
      - delivered
      - error
      - route
      type: object
    AlertRoute:
      properties:
        enabled:
          type: boolean
        health:
          enum:
          - ok
          - needs_reconnect
          - channel_missing
          type: string
        kinds:
          items:
            enum:
            - reply.interested
            - delivery.unknown
            - run.failed
            - request.pending
            - secrets.vault_unreachable
            - work.started
            - work.delivered
            - project.ready_for_approval
            - project.finished
            type: string
          type: array
        lastError:
          type:
          - string
          - 'null'
        lastErrorAt:
          type:
          - string
          - 'null'
        provider:
          enum:
          - slack
          - telegram
          type: string
        slackChannelId:
          type:
          - string
          - 'null'
        slackChannelName:
          type:
          - string
          - 'null'
        slackChannelPrivate:
          type: boolean
        slackTeamId:
          type:
          - string
          - 'null'
        updatedAt:
          type:
          - string
          - 'null'
      required:
      - provider
      - slackTeamId
      - slackChannelId
      - slackChannelName
      - slackChannelPrivate
      - kinds
      - enabled
      - health
      - lastError
      - lastErrorAt
      - updatedAt
      type: object
    SlackChannelPage:
      properties:
        channels:
          items:
            properties:
              id:
                type: string
              isMember:
                type: boolean
              isPrivate:
                type: boolean
              memberCount:
                anyOf:
                - maximum: 9007199254740991
                  minimum: -9007199254740991
                  type: integer
                - type: 'null'
              name:
                type: string
            required:
            - id
            - name
            - isPrivate
            - isMember
            - memberCount
            type: object
          type: array
        nextCursor:
          type:
          - string
          - 'null'
      required:
      - channels
      - nextCursor
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    AlertRouteRemoved:
      properties:
        removed:
          type: boolean
      required:
      - removed
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey