openapi: 3.2.0
info:
  title: HyperDX External Alerts API
  description: API for managing HyperDX alerts and dashboards
  version: 2.0.0
servers:
- url: /
  description: Your HyperDX instance (http://<host>:<port>)
security:
- BearerAuth: []
tags:
- name: Alerts
  description: Endpoints for managing monitoring alerts
paths:
  /api/v2/alerts/{id}:
    get:
      summary: Get Alert
      description: Retrieves a specific alert by ID
      operationId: getAlert
      tags:
      - Alerts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert ID
        example: 65f5e4a3b9e77c001a123456
      responses:
        '200':
          description: Successfully retrieved alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponseEnvelope'
              examples:
                alertResponse:
                  summary: Single alert response
                  value:
                    data:
                      id: 65f5e4a3b9e77c001a123456
                      threshold: 80
                      interval: 5m
                      thresholdType: above
                      source: tile
                      state: ALERT
                      channel:
                        type: webhook
                        webhookId: 65f5e4a3b9e77c001a789012
                      teamId: 65f5e4a3b9e77c001a345678
                      tileId: 65f5e4a3b9e77c001a901234
                      dashboardId: 65f5e4a3b9e77c001a567890
                      numConsecutiveWindows: 3
                      createdAt: '2023-03-15T10:20:30.000Z'
                      updatedAt: '2023-03-15T14:25:10.000Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      summary: Update Alert
      description: Updates an existing alert
      operationId: updateAlert
      tags:
      - Alerts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert ID
        example: 65f5e4a3b9e77c001a123456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlertRequest'
            examples:
              updateAlert:
                summary: Update alert properties
                value:
                  threshold: 500
                  interval: 1h
                  thresholdType: above
                  source: tile
                  dashboardId: 65f5e4a3b9e77c001a567890
                  tileId: 65f5e4a3b9e77c001a901234
                  channel:
                    type: webhook
                    webhookId: 65f5e4a3b9e77c001a789012
                  name: Updated Alert Name
                  message: Updated threshold and interval
      responses:
        '200':
          description: Successfully updated alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponseEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      summary: Delete Alert
      description: Deletes an alert
      operationId: deleteAlert
      tags:
      - Alerts
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Alert ID
        example: 65f5e4a3b9e77c001a123456
      responses:
        '200':
          description: Successfully deleted alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
              example: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Alert not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v2/alerts:
    get:
      summary: List Alerts
      description: Retrieves alerts for the authenticated team (paginated). Results are capped at `limit` (default and maximum 1000). When more records exist than are returned, `meta.total` exceeds `data.length`; clients with large collections must page with `limit`/`offset` to retrieve them all.
      operationId: listAlerts
      tags:
      - Alerts
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 1000
        description: Maximum number of alerts to return.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of alerts to skip before returning results.
      responses:
        '200':
          description: Successfully retrieved alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsListResponse'
              examples:
                alertsList:
                  summary: List of alerts
                  value:
                    data:
                    - id: 65f5e4a3b9e77c001a123456
                      threshold: 100
                      interval: 15m
                      thresholdType: above
                      source: tile
                      state: OK
                      channel:
                        type: webhook
                        webhookId: 65f5e4a3b9e77c001a789012
                      teamId: 65f5e4a3b9e77c001a345678
                      tileId: 65f5e4a3b9e77c001a901234
                      dashboardId: 65f5e4a3b9e77c001a567890
                      createdAt: '2023-01-01T00:00:00.000Z'
                      updatedAt: '2023-01-01T00:00:00.000Z'
                    meta:
                      total: 1
                      limit: 1000
                      offset: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Create Alert
      description: Creates a new alert
      operationId: createAlert
      tags:
      - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlertRequest'
            examples:
              tileAlert:
                summary: Create a tile-based alert
                value:
                  dashboardId: 65f5e4a3b9e77c001a567890
                  tileId: 65f5e4a3b9e77c001a901234
                  threshold: 100
                  interval: 1h
                  source: tile
                  thresholdType: above
                  channel:
                    type: webhook
                    webhookId: 65f5e4a3b9e77c001a789012
                  name: Error Spike Alert
                  message: Error rate has exceeded 100 in the last hour
                  numConsecutiveWindows: 3
              multiChannelAlert:
                summary: Create an alert that notifies several webhooks
                value:
                  savedSearchId: 65f5e4a3b9e77c001a345678
                  threshold: 10
                  interval: 5m
                  source: saved_search
                  thresholdType: above
                  channels:
                  - type: webhook
                    webhookId: 65f5e4a3b9e77c001a789012
                  - type: webhook
                    webhookId: 65f5e4a3b9e77c001a789013
                  name: Error Spike Alert
      responses:
        '200':
          description: Successfully created alert
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponseEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AlertsListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          description: List of alert objects.
          items:
            $ref: '#/components/schemas/AlertResponse'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
          description: Pagination metadata for this result page.
    AlertState:
      type: string
      enum:
      - ALERT
      - OK
      - INSUFFICIENT_DATA
      - DISABLED
      - PENDING
      description: Current alert state.
    AlertChannelWebhook:
      type: object
      required:
      - type
      - webhookId
      properties:
        type:
          $ref: '#/components/schemas/AlertChannelType'
          description: Channel type. Must be "webhook" for webhook alerts.
        webhookId:
          type: string
          description: Webhook destination ID.
          example: 65f5e4a3b9e77c001a789012
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: 'NOT_FOUND: Alert not found'
    EmptyResponse:
      type: object
      properties: {}
    AlertSilenced:
      type: object
      description: Silencing metadata.
      properties:
        by:
          type:
          - string
          - 'null'
          description: User ID who silenced the alert.
          example: 65f5e4a3b9e77c001a234567
        at:
          type: string
          description: Silence start timestamp.
          format: date-time
          example: '2026-03-19T08:00:00.000Z'
        until:
          type: string
          description: Silence end timestamp.
          format: date-time
          example: '2026-03-20T08:00:00.000Z'
    AlertExecutionError:
      type: object
      description: An error recorded during a recent alert execution.
      required:
      - timestamp
      - type
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the error occurred.
          example: '2026-04-17T12:00:00.000Z'
        type:
          $ref: '#/components/schemas/AlertErrorType'
          description: Category of the error.
          example: QUERY_ERROR
        message:
          type: string
          description: Human-readable error message.
          example: Query timed out after 30s
    AlertResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AlertResponse'
          description: The alert object.
    Alert:
      type: object
      properties:
        dashboardId:
          type:
          - string
          - 'null'
          description: Dashboard ID for tile-based alerts.
          example: 65f5e4a3b9e77c001a567890
        tileId:
          type:
          - string
          - 'null'
          description: Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.
          example: 65f5e4a3b9e77c001a901234
        savedSearchId:
          type:
          - string
          - 'null'
          description: Saved search ID for saved_search alerts.
          example: 65f5e4a3b9e77c001a345678
        groupBy:
          type:
          - string
          - 'null'
          description: Group-by key for saved search alerts.
          example: ServiceName
        threshold:
          type: number
          description: Threshold value for triggering the alert. For between and not_between threshold types, this is the lower bound.
          example: 100
        thresholdMax:
          type:
          - number
          - 'null'
          description: Upper bound for between and not_between threshold types. Required when thresholdType is between or not_between, must be >= threshold.
          example: 500
        interval:
          $ref: '#/components/schemas/AlertInterval'
          description: Evaluation interval for the alert.
          example: 1h
        scheduleOffsetMinutes:
          type:
          - integer
          - 'null'
          minimum: 0
          description: Offset from the interval boundary in minutes. For example, 2 with a 5m interval evaluates windows at :02, :07, :12, etc. (UTC).
          example: 2
        scheduleStartAt:
          type:
          - string
          - 'null'
          format: date-time
          description: Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.
          example: '2026-02-08T10:00:00.000Z'
        source:
          $ref: '#/components/schemas/AlertSource'
          description: Alert source type (tile-based or saved search).
          example: tile
        thresholdType:
          $ref: '#/components/schemas/AlertThresholdType'
          description: Threshold comparison direction.
          example: above
        channel:
          $ref: '#/components/schemas/AlertChannel'
          description: First notification channel, mirrored from "channels" for pre-multi-channel clients.
        channels:
          $ref: '#/components/schemas/AlertChannels'
          description: All notification channels to trigger when the alert fires or resolves.
        name:
          type:
          - string
          - 'null'
          description: Human-friendly alert name.
          example: Test Alert
        message:
          type:
          - string
          - 'null'
          description: Alert message template.
          example: Test Alert Message
        note:
          type:
          - string
          - 'null'
          description: Freeform note for the alert. Supports markdown formatting.
          minLength: 1
          maxLength: 4096
          example: Threshold raised from 50 to 100 on 2026-01-15. See [runbook](https://wiki.example.com/runbook).
        numConsecutiveWindows:
          type:
          - integer
          - 'null'
          minimum: 1
          description: Fire the alert only after its condition has been met for this many consecutive evaluation windows. While the condition is met but fewer than this many consecutive windows have violated, the alert is in the PENDING state.
          example: 3
    PaginationMeta:
      type: object
      required:
      - total
      - limit
      - offset
      properties:
        total:
          type: integer
          description: Total number of items matching the query, ignoring pagination.
          example: 142
        limit:
          type: integer
          description: Maximum number of items returned in this page.
          example: 50
        offset:
          type: integer
          description: Number of items skipped before this page.
          example: 100
    AlertThresholdType:
      type: string
      enum:
      - above
      - below
      - above_exclusive
      - below_or_equal
      - equal
      - not_equal
      - between
      - not_between
      description: Threshold comparison direction.
    AlertResponse:
      allOf:
      - $ref: '#/components/schemas/Alert'
      - type: object
        properties:
          id:
            type: string
            description: Unique alert identifier.
            example: 65f5e4a3b9e77c001a123456
          state:
            $ref: '#/components/schemas/AlertState'
            description: Current alert state.
            example: ALERT
          teamId:
            type: string
            description: Team identifier.
            example: 65f5e4a3b9e77c001a345678
          silenced:
            $ref: '#/components/schemas/AlertSilenced'
            description: Silencing metadata.
          executionErrors:
            type:
            - array
            - 'null'
            description: Errors recorded during the most recent alert execution, if any.
            items:
              $ref: '#/components/schemas/AlertExecutionError'
          createdAt:
            type:
            - string
            - 'null'
            format: date-time
            description: Creation timestamp.
            example: '2023-01-01T00:00:00.000Z'
          updatedAt:
            type:
            - string
            - 'null'
            format: date-time
            description: Last update timestamp.
            example: '2023-01-01T00:00:00.000Z'
    AlertChannels:
      type: array
      description: 'Notification channels to trigger when the alert fires or resolves. Between 1 and 10 channels; duplicates are rejected.

        '
      minItems: 1
      maxItems: 10
      items:
        $ref: '#/components/schemas/AlertChannel'
    UpdateAlertRequest:
      allOf:
      - $ref: '#/components/schemas/Alert'
      - type: object
        description: 'At least one of "channel" or "channels" must be provided. Sending both is allowed only when "channel" matches the first entry of "channels", so a response body can be echoed back unchanged. Responses always include both, with "channel" mirroring the first entry of "channels". Updates replace the alert''s configuration rather than merging it: sending only the legacy "channel" field for an alert that has several channels reduces it to that one channel. Fetch the alert and resend the complete "channels" array to preserve them.

          '
        required:
        - threshold
        - interval
        - thresholdType
    AlertChannelType:
      type: string
      enum:
      - webhook
      description: Channel type.
    AlertErrorType:
      type: string
      enum:
      - QUERY_ERROR
      - QUERY_TIMEOUT
      - WEBHOOK_ERROR
      - INVALID_ALERT
      - UNKNOWN
      description: Category of error recorded during alert execution.
    AlertInterval:
      type: string
      enum:
      - 1m
      - 5m
      - 15m
      - 30m
      - 1h
      - 6h
      - 12h
      - 1d
      description: Evaluation interval.
    AlertSource:
      type: string
      enum:
      - saved_search
      - tile
      description: Alert source type.
    AlertChannel:
      oneOf:
      - $ref: '#/components/schemas/AlertChannelWebhook'
      discriminator:
        propertyName: type
    CreateAlertRequest:
      allOf:
      - $ref: '#/components/schemas/Alert'
      - type: object
        description: 'At least one of "channel" or "channels" must be provided. Sending both is allowed only when "channel" matches the first entry of "channels", so a response body can be echoed back unchanged. Responses always include both, with "channel" mirroring the first entry of "channels".

          '
        required:
        - threshold
        - interval
        - thresholdType
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key