openapi: 3.2.0
info:
  title: HyperDX External Charts 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: Charts
  description: Endpoints for querying chart data
paths:
  /api/v2/charts/series:
    post:
      summary: Query Chart Series Data
      description: Retrieves time series data based on configured series parameters
      operationId: queryChartSeries
      tags:
      - Charts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SeriesQueryRequest'
            examples:
              basicTimeSeries:
                summary: Basic time series query
                value:
                  startTime: 1647014400000
                  endTime: 1647100800000
                  granularity: 1h
                  series:
                  - sourceId: 65f5e4a3b9e77c001a123456
                    aggFn: count
                    where: SeverityText:error
                    groupBy: []
              multiSeriesWithGroupBy:
                summary: Multiple series with group by
                value:
                  startTime: 1647014400000
                  endTime: 1647100800000
                  granularity: 15m
                  series:
                  - sourceId: 65f5e4a3b9e77c001a123456
                    aggFn: count
                    where: SeverityText:error
                    groupBy:
                    - service
                  - sourceId: 65f5e4a3b9e77c001a123456
                    aggFn: avg
                    field: duration
                    where: SeverityText:error
                    groupBy:
                    - service
              multiSourceSeries:
                summary: Series from multiple sources
                value:
                  startTime: 1647014400000
                  endTime: 1647100800000
                  granularity: 5m
                  series:
                  - sourceId: 65f5e4a3b9e77c001a123456
                    aggFn: count
                    where: SeverityText:error
                    groupBy: []
                  - sourceId: 65f5e4a3b9e77c001a789012
                    aggFn: avg
                    metricName: http_requests_total
                    metricDataType: gauge
                    where: service:api
                    groupBy: []
              metricSeries:
                summary: Metric data series
                value:
                  startTime: 1647014400000
                  endTime: 1647100800000
                  granularity: 5m
                  series:
                  - sourceId: 65f5e4a3b9e77c001a789012
                    aggFn: avg
                    metricName: http_requests_total
                    metricDataType: gauge
                    where: service:api
                    groupBy: []
      responses:
        '200':
          description: Successfully retrieved time series data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeriesResponse'
              examples:
                timeSeriesData:
                  summary: Time series data points
                  value:
                    data:
                    - ts_bucket: 1647014400000
                      series_0.data: 42
                    - ts_bucket: 1647018000000
                      series_0.data: 37
                    - ts_bucket: 1647021600000
                      series_0.data: 53
                groupedTimeSeriesData:
                  summary: Grouped time series data
                  value:
                    data:
                    - ts_bucket: 1647014400000
                      series_0.data: 15
                      group:
                      - api
                    - ts_bucket: 1647014400000
                      series_0.data: 8
                      group:
                      - frontend
                    - ts_bucket: 1647018000000
                      series_0.data: 22
                      group:
                      - api
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              examples:
                invalidParams:
                  value:
                    error: All series must have the same groupBy fields
                invalidTimestamp:
                  value:
                    error: Timestamp must be in milliseconds
        '403':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Team context missing
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Source not found
        '500':
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Internal server error
components:
  schemas:
    SeriesDataPoint:
      type: object
      properties:
        ts_bucket:
          type: number
          description: Timestamp of the data point (bucket start time)
          example: 1647014400000
        series_0.data:
          type: number
          description: Value for the first series
          example: 42
        series_1.data:
          type: number
          description: Value for the second series
          example: 18
        group:
          type: array
          description: Group by values if groupBy was specified
          items:
            type: string
          example:
          - api
          - prod-host-1
    ChartSeries:
      type: object
      required:
      - sourceId
      - aggFn
      - where
      - groupBy
      properties:
        sourceId:
          type: string
          description: ID of the data source for this series
          example: 65f5e4a3b9e77c001a123456
        aggFn:
          type: string
          description: Aggregation function to use on the data
          enum:
          - avg
          - count
          - count_distinct
          - last_value
          - max
          - min
          - quantile
          - sum
          example: count
        field:
          type: string
          description: Field to aggregate
          example: duration
        where:
          type: string
          description: Filter condition in Lucene query syntax
          example: service:api AND level:error
        whereLanguage:
          type: string
          description: Query language used in the where clause
          enum:
          - lucene
          - sql
          example: lucene
        groupBy:
          type: array
          description: Fields to group the results by
          items:
            type: string
          example:
          - service
          - host
        metricName:
          type: string
          description: Name of the metric (for metric data sources)
          example: http_requests_total
        metricDataType:
          type: string
          description: Type of metric data
          enum:
          - sum
          - gauge
          - histogram
          example: gauge
    SeriesResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of data points for the series
          items:
            $ref: '#/components/schemas/SeriesDataPoint'
    SeriesQueryRequest:
      type: object
      required:
      - series
      - startTime
      - endTime
      properties:
        series:
          type: array
          description: Array of series configurations
          items:
            $ref: '#/components/schemas/ChartSeries'
          minItems: 1
          maxItems: 5
        startTime:
          type: number
          description: Start timestamp in milliseconds
          example: 1647014400000
        endTime:
          type: number
          description: End timestamp in milliseconds
          example: 1647100800000
        granularity:
          type: string
          description: Time bucket size for aggregations
          enum:
          - 30s
          - 1m
          - 5m
          - 10m
          - 15m
          - 30m
          - 1h
          - 2h
          - 6h
          - 12h
          - 1d
          - 2d
          - 7d
          - 30d
          - auto
          example: 1h
        seriesReturnType:
          type: string
          description: Format of the returned data
          enum:
          - ratio
          - column
          example: column
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key