HyperDX Dashboards API

openapi: 3.2.0
info:
  title: HyperDX External Dashboards 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: Dashboards
  description: Endpoints for managing dashboards and their visualizations
paths:
  /api/v2/dashboards:
    get:
      summary: List Dashboards
      description: Retrieves a list of all dashboards for the authenticated team
      operationId: listDashboards
      tags:
      - Dashboards
      responses:
        '200':
          description: Successfully retrieved dashboards
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardsListResponse'
              examples:
                dashboards:
                  summary: Dashboards list response
                  value:
                    data:
                    - id: 65f5e4a3b9e77c001a567890
                      name: Infrastructure Monitoring
                      tiles:
                      - id: 65f5e4a3b9e77c001a901234
                        name: Server CPU
                        x: 0
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: line
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: avg
                            valueExpression: cpu.usage
                            where: host:server-01
                      tags:
                      - infrastructure
                      - monitoring
                      filters:
                      - id: 65f5e4a3b9e77c001a301001
                        type: QUERY_EXPRESSION
                        name: Environment
                        expression: environment
                        sourceId: 65f5e4a3b9e77c001a111111
                    - id: 65f5e4a3b9e77c001a567891
                      name: API Monitoring
                      tiles:
                      - id: 65f5e4a3b9e77c001a901235
                        name: API Errors
                        x: 0
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: table
                          sourceId: 65f5e4a3b9e77c001a111112
                          select:
                          - aggFn: count
                            where: level:error
                          groupBy: service
                          orderBy: count DESC
                      tags:
                      - api
                      - monitoring
                      filters:
                      - id: 65f5e4a3b9e77c001a301002
                        type: QUERY_EXPRESSION
                        name: Service
                        expression: service_name
                        sourceId: 65f5e4a3b9e77c001a111112
        '401':
          description: Unauthorized
    post:
      summary: Create Dashboard
      description: Creates a new dashboard
      operationId: createDashboard
      tags:
      - Dashboards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDashboardRequest'
            examples:
              simpleTimeSeriesDashboard:
                summary: Dashboard with a line chart
                value:
                  name: API Monitoring Dashboard
                  tiles:
                  - name: API Request Volume
                    x: 0
                    y: 0
                    w: 6
                    h: 3
                    config:
                      displayType: line
                      sourceId: 65f5e4a3b9e77c001a111111
                      select:
                      - aggFn: count
                        where: service:api
                  tags:
                  - api
                  - monitoring
                  filters:
                  - type: QUERY_EXPRESSION
                    name: Environment
                    expression: environment
                    sourceId: 65f5e4a3b9e77c001a111111
              complexDashboard:
                summary: Dashboard with multiple chart types
                value:
                  name: Service Health Overview
                  tiles:
                  - name: Request Count
                    x: 0
                    y: 0
                    w: 6
                    h: 3
                    config:
                      displayType: line
                      sourceId: 65f5e4a3b9e77c001a111111
                      select:
                      - aggFn: count
                        where: service:backend
                  - name: Error Distribution
                    x: 6
                    y: 0
                    w: 6
                    h: 3
                    config:
                      displayType: table
                      sourceId: 65f5e4a3b9e77c001a111111
                      select:
                      - aggFn: count
                        where: level:error
                      groupBy: errorType
                      orderBy: count DESC
                  tags:
                  - service-health
                  - production
                  filters:
                  - type: QUERY_EXPRESSION
                    name: Service
                    expression: service_name
                    sourceId: 65f5e4a3b9e77c001a111111
      responses:
        '200':
          description: Successfully created dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardResponseEnvelope'
              examples:
                createdDashboard:
                  summary: Created dashboard response
                  value:
                    data:
                      id: 65f5e4a3b9e77c001a567890
                      name: API Monitoring Dashboard
                      tiles:
                      - id: 65f5e4a3b9e77c001a901234
                        name: API Request Volume
                        x: 0
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: line
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: count
                            where: service:api
                      tags:
                      - api
                      - monitoring
                      filters:
                      - id: 65f5e4a3b9e77c001a301004
                        type: QUERY_EXPRESSION
                        name: Environment
                        expression: environment
                        sourceId: 65f5e4a3b9e77c001a111111
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Could not find the following source IDs: 68fa86308aa879b977aa6af6'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '500':
          description: Server error or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Dashboard validation failed: name is required'
  /api/v2/dashboards/{id}:
    get:
      summary: Get Dashboard
      description: Retrieves a specific dashboard by ID
      operationId: getDashboard
      tags:
      - Dashboards
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Dashboard ID
        example: 65f5e4a3b9e77c001a567890
      responses:
        '200':
          description: Successfully retrieved dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardResponseEnvelope'
              examples:
                dashboard:
                  summary: Single dashboard response
                  value:
                    data:
                      id: 65f5e4a3b9e77c001a567890
                      name: Infrastructure Monitoring
                      tiles:
                      - id: 65f5e4a3b9e77c001a901234
                        name: Server CPU
                        x: 0
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: line
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: avg
                            valueExpression: cpu.usage
                            where: host:server-01
                      - id: 65f5e4a3b9e77c001a901235
                        name: Memory Usage
                        x: 6
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: line
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: avg
                            valueExpression: memory.usage
                            where: host:server-01
                      tags:
                      - infrastructure
                      - monitoring
                      filters:
                      - id: 65f5e4a3b9e77c001a301003
                        type: QUERY_EXPRESSION
                        name: Environment
                        expression: environment
                        sourceId: 65f5e4a3b9e77c001a111111
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '404':
          description: Dashboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Dashboard not found
    put:
      summary: Update Dashboard
      description: 'Updates an existing dashboard.


        **Concurrency:** This endpoint does not support optimistic

        concurrency control. Concurrent PUT requests for the same

        dashboard may silently overwrite each other, which can leave

        orphan tile-to-container references on layout-shape edits.

        Clients should serialize edits to a given dashboard.

        '
      operationId: updateDashboard
      tags:
      - Dashboards
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Dashboard ID
        example: 65f5e4a3b9e77c001a567890
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDashboardRequest'
            examples:
              updateDashboard:
                summary: Update dashboard properties and tiles
                value:
                  name: Updated Dashboard Name
                  tiles:
                  - id: 65f5e4a3b9e77c001a901234
                    name: Updated Line Chart
                    x: 0
                    y: 0
                    w: 6
                    h: 3
                    config:
                      displayType: line
                      sourceId: 65f5e4a3b9e77c001a111111
                      select:
                      - aggFn: count
                        where: level:error
                  - id: new-tile-123
                    name: New Number Chart
                    x: 6
                    y: 0
                    w: 6
                    h: 3
                    config:
                      displayType: number
                      sourceId: 65f5e4a3b9e77c001a111111
                      select:
                      - aggFn: count
                        where: level:info
                  tags:
                  - production
                  - updated
                  filters:
                  - id: 65f5e4a3b9e77c001a301005
                    type: QUERY_EXPRESSION
                    name: Environment
                    expression: environment
                    sourceId: 65f5e4a3b9e77c001a111111
      responses:
        '200':
          description: Successfully updated dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardResponseEnvelope'
              examples:
                updatedDashboard:
                  summary: Updated dashboard response
                  value:
                    data:
                      id: 65f5e4a3b9e77c001a567890
                      name: Updated Dashboard Name
                      tiles:
                      - id: 65f5e4a3b9e77c001a901234
                        name: Updated Line Chart
                        x: 0
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: line
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: count
                            where: level:error
                      - id: new-tile-123
                        name: New Number Chart
                        x: 6
                        y: 0
                        w: 6
                        h: 3
                        config:
                          displayType: number
                          sourceId: 65f5e4a3b9e77c001a111111
                          select:
                          - aggFn: count
                            where: level:info
                      tags:
                      - production
                      - updated
                      filters:
                      - id: 65f5e4a3b9e77c001a301005
                        type: QUERY_EXPRESSION
                        name: Environment
                        expression: environment
                        sourceId: 65f5e4a3b9e77c001a111111
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Could not find the following source IDs: 68fa86308aa879b977aa6af6'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '404':
          description: Dashboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Dashboard not found
        '500':
          description: Server error or validation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Invalid dashboard configuration
    delete:
      summary: Delete Dashboard
      description: Deletes a dashboard
      operationId: deleteDashboard
      tags:
      - Dashboards
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Dashboard ID
        example: 65f5e4a3b9e77c001a567890
      responses:
        '200':
          description: Successfully deleted dashboard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
              example: {}
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
        '404':
          description: Dashboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Dashboard not found
  /api/v2/dashboards/validate:
    post:
      summary: Validate Dashboard
      description: 'Validates a dashboard body against the same schema and tile rules used

        by POST /api/v2/dashboards. The dashboard is **never persisted**. Use

        this endpoint at plan time (e.g. from a Terraform provider) to check

        that a dashboard configuration is valid before applying it.

        '
      operationId: validateDashboard
      tags:
      - Dashboards
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDashboardRequest'
      responses:
        '200':
          description: 'Validation result. HTTP 200 is always returned for valid **and**

            invalid bodies — a non-200 response means the request itself

            failed (auth, server error, etc.).

            '
          content:
            application/json:
              schema:
                type: object
                required:
                - valid
                - errors
                - normalized
                properties:
                  valid:
                    type: boolean
                    description: True when the body passes all validation rules.
                  errors:
                    type: array
                    description: Validation errors. Empty when valid is true.
                    items:
                      type: object
                      required:
                      - path
                      - message
                      properties:
                        path:
                          type: string
                          description: Dot-separated field path, or empty string for top-level errors.
                        message:
                          type: string
                          description: Human-readable error description.
                  normalized:
                    type:
                    - object
                    - 'null'
                    description: 'The parsed dashboard body with defaults applied (no

                      persistence, so no server-assigned tile IDs). Populated

                      when valid is true, null when valid is false.

                      '
              examples:
                valid:
                  summary: Valid dashboard body
                  value:
                    valid: true
                    errors: []
                    normalized:
                      name: My Dashboard
                      tiles: []
                invalid:
                  summary: Invalid dashboard body
                  value:
                    valid: false
                    errors:
                    - path: name
                      message: Required
                    normalized: null
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Unauthorized access. API key is missing or invalid.
components:
  schemas:
    DashboardResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DashboardResponse'
          description: The dashboard object.
    OnClick:
      description: 'Link-out configuration applied when a user clicks a row of a table tile. Only table tiles (builder or raw SQL) currently support onClick. When target.mode is "id", the referenced source (type=search) or dashboard (type=dashboard) must already exist for the team.

        '
      oneOf:
      - $ref: '#/components/schemas/OnClickSearch'
      - $ref: '#/components/schemas/OnClickDashboard'
      - $ref: '#/components/schemas/OnClickExternal'
      discriminator:
        propertyName: type
        mapping:
          search: '#/components/schemas/OnClickSearch'
          dashboard: '#/components/schemas/OnClickDashboard'
          external: '#/components/schemas/OnClickExternal'
    Formula:
      type: object
      required:
      - expression
      description: 'A derived series computed from the chart''s select items via a letter-ref arithmetic expression (metric, log, and trace sources only). "A" refers to select[0], "B" to select[1], and so on. The grammar supports + - * /, parentheses, and numeric constants; expressions are parsed and validated, never passed through as raw SQL. Division by zero or a missing operand yields NULL (rendered as a gap).

        '
      properties:
        expression:
          type: string
          maxLength: 1024
          description: 'Arithmetic expression over the select items by position, e.g. "A / (A + B) * 100" for a success-rate percentage.

            '
          example: A / (A + B) * 100
        alias:
          type: string
          description: 'Display label for the formula series in chart legends and column headers. Falls back to the raw expression text when unset.

            '
          example: Success rate %
        numberFormat:
          $ref: '#/components/schemas/NumberFormat'
          description: 'Per-series number formatting options for the formula series.

            '
    CreateDashboardRequest:
      type: object
      required:
      - name
      - tiles
      properties:
        name:
          type: string
          maxLength: 1024
          description: Dashboard name.
          example: New Dashboard
        tiles:
          type: array
          description: List of tiles/charts to include in the dashboard.
          maxItems: 500
          items:
            $ref: '#/components/schemas/TileInput'
        tags:
          type: array
          description: Tags for organizing and filtering dashboards.
          items:
            type: string
            maxLength: 32
          maxItems: 50
          example:
          - development
        filters:
          type: array
          description: 'Dropdown filters added to the dashboard. Each one broadcasts

            its selected value as a condition, acts as a variable which

            can be referenced in tile queries, or both.

            '
          items:
            $ref: '#/components/schemas/FilterInput'
        savedQuery:
          type:
          - string
          - 'null'
          description: Optional default dashboard query to persist on the dashboard.
          example: service.name = 'api'
        savedQueryLanguage:
          $ref: '#/components/schemas/QueryLanguage'
          description: Query language used by savedQuery.
          default: lucene
          example: sql
        savedFilterValues:
          type: array
          description: Optional default dashboard filter values to persist on the dashboard.
          items:
            $ref: '#/components/schemas/SavedFilterValue'
        containers:
          type: array
          description: Optional grouping containers. Each tile may join a container via tile.containerId, and a tab inside it via tile.tabId.
          maxItems: 50
          items:
            $ref: '#/components/schemas/DashboardContainer'
    DashboardContainerTab:
      type: object
      description: A single tab inside a dashboard container. Tiles join a tab via tabId.
      required:
      - id
      - title
      properties:
        id:
          type: string
          minLength: 1
          maxLength: 256
          description: Unique identifier for the tab within its container.
          example: errors
        title:
          type: string
          minLength: 1
          maxLength: 256
          description: Display title for the tab.
          example: Errors
    NumberChartConfig:
      description: 'Single big-number chart. Omit configType for the builder variant (requires sourceId and select). Set configType to "sql" for the Raw SQL variant (requires connectionId and sqlTemplate).

        '
      oneOf:
      - $ref: '#/components/schemas/NumberBuilderChartConfig'
      - $ref: '#/components/schemas/NumberRawSqlChartConfig'
      discriminator:
        propertyName: configType
        mapping:
          sql: '#/components/schemas/NumberRawSqlChartConfig'
    NumberBuilderChartConfig:
      type: object
      required:
      - displayType
      - sourceId
      - select
      description: Builder configuration for a single big-number chart.
      properties:
        displayType:
          type: string
          enum:
          - number
          description: Display type discriminator. Must be "number" for single big-number charts.
          example: number
        sourceId:
          type: string
          description: ID of the data source to query.
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          minItems: 1
          maxItems: 20
          description: 'Exactly one aggregated value to display as a single number — unless "formulas" is set, in which case the select items are the formula''s operands and the (single) formula value is displayed instead.

            '
          items:
            $ref: '#/components/schemas/SelectItem'
        formulas:
          type: array
          maxItems: 1
          description: 'A single derived value computed from the select items via letter-ref arithmetic ("A" = select[0], "B" = select[1], ...). Metric, log, and trace sources only. Number tiles display the formula value and always hide the operand series.

            '
          items:
            $ref: '#/components/schemas/Formula'
        numberFormat:
          $ref: '#/components/schemas/NumberFormat'
          description: Number formatting options for displayed values.
        color:
          $ref: '#/components/schemas/ChartPaletteToken'
          description: Optional static color applied to the displayed number.
        colorRules:
          type: array
          maxItems: 10
          description: 'Ordered conditional color rules evaluated against the displayed value (last match wins). Falls back to color, then the default text color when no rule matches.

            '
          items:
            $ref: '#/components/schemas/NumberTileColorCondition'
        backgroundChart:
          $ref: '#/components/schemas/BackgroundChart'
          description: 'Optional background trend sparkline drawn behind the value.

            '
    PieBuilderChartConfig:
      type: object
      required:
      - displayType
      - sourceId
      - select
      description: Builder configuration for a pie chart tile. Each slice represents one group value.
      properties:
        displayType:
          type: string
          enum:
          - pie
          description: Display type discriminator. Must be "pie" for pie charts.
          example: pie
        sourceId:
          type: string
          description: ID of the data source to query.
          example: 65f5e4a3b9e77c001a111111
        select:
          type: array
          minItems: 1
          maxItems: 1
          description: Exactly one aggregated value used to size each pie slice.
          items:
            $ref: '#/components/schemas/SelectItem'
        groupBy:
          type: string
          maxLength: 10000
          description: Field expression to group results by (one slice per group value).
          example: service
        orderBy:
          type: string
          maxLength: 10000
          description: 'Optional custom SQL ORDER BY expression (raw SQL). Overrides the default value-descending ordering and, when combined with "limit", controls which slices are kept.

            '
          example: '"Count" DESC'
        numberFormat:
          $ref: '#/components/schemas/NumberFormat'
          description: Number formatting options for displayed values.
        limit:
          type: integer
          minimum: 0
          description: 'Maximum number of slices (SQL LIMIT). Without a custom "orderBy" the query keeps the groups with the largest aggregated values; with an "orderBy" it keeps the first slices in that order. Omit or set 0 to fetch all groups.

            '
          example: 10
    BackgroundChart:
      type: object
      required:
      - type
      description: 'Optional background trend sparkline drawn behind a number tile''s value, derived from a time-bucketed version of the tile''s query. Builder number tiles only (raw SQL number tiles have no time dimension to bucket).

        '
      properties:
        type:
          type: string
          enum:
          - line
          - area
          description: Sparkline shape.
          example: line
        color:
          $ref: '#/components/schemas/ChartPaletteToken'
          description: 'Optional palette-token override for the sparkline. When unset the sparkline inherits the tile''s static color.

            '
    CategoricalBarRawSqlChartConfig:
      description: Raw SQL configuration for a categorical bar chart.
      allOf:
      - $ref: '#/components/schemas/RawSqlChartConfigBase'
      - type: object
        required:
        - displayType
        properties:
          displayType:
            type: string
            enum:
            - bar
            description: Display as a categorical bar chart.
            example: bar
    Error:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: 'NOT_FOUND: Alert not found'
    TimeSeriesDisplayType:
      type: string
      enum:
      - stacked_bar
      - line
      description: Visual representation type for the time series.
    QueryLanguage:
      type: string
      enum:
      - sql
      - lucene
      description: Query language for the where clause.
    EmptyResponse:
      type: object
      properties: {}
    OnClickSearch:
      type: object
      required:
      - type
      - target
      description: Link-out that navigates to the HyperDX search view.
      properties:
        type:
          type: string
          enum:
          - search
          description: OnClick variant discriminator. Must be "search" for search link-outs.
          example: search
        target:
          $ref: '#/components/schemas/OnClickTarget'
          description: The source to navigate to.
        whereTemplate:
          type: string
          description: Optional WHERE clause template applied to the destination search.
          example: ServiceName = '{{ServiceName}}'
        whereLanguage:
          $ref: '#/components/schemas/QueryLanguage'
          description: Language of the rendered whereTemplate.
        filters:
          type: array
          description: Optional dashboard filter templates rendered against the clicked row.
          items:
            $ref: '#/components/schemas/OnClickFilterTemplate'
    MarkdownChartConfig:
      type: object
      required:
      - displayType
      description: Configuration for a freeform Markdown text tile.
      properties:
        displayType:
          type: string
          enum:
          - markdown
          description: Display type discriminator. Must be "markdown" for markdown text tiles.
          example: markdown
        markdown:
          type: string
          maxLength: 50000
          description: Markdown content to render inside the tile.
          example: '# Dashboard Title


            This is a markdown widget.'
    NumberFormatOutput:
      type: string
      enum:
      - currency
      - percent
      - byte
      - time
      - number
      - data_rate
      - throughput
      - duration
      description: Output format type (currency, percent, byte, time, number, data_rate, throughput, duration).
    BarBuilderChartConfig:
      type: object
      required:
      - displayType
      - sourceId
      -

# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hyperdx/refs/heads/main/openapi/hyperdx-dashboards-api-openapi.yml