HyperDX Sources API

openapi: 3.2.0
info:
  title: HyperDX External Sources 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: Sources
  description: Endpoints for managing data sources
paths:
  /api/v2/sources:
    get:
      summary: List Sources
      description: Retrieves a list of all sources for the authenticated team
      operationId: listSources
      tags:
      - Sources
      responses:
        '200':
          description: Successfully retrieved sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourcesListResponse'
        '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 Source
      description: 'Creates a new source.


        The request body is a source object without the `id` field. If an

        `id` is sent anyway it is silently ignored (stripped before

        validation — the request is never rejected because of it).

        Granularity fields

        (`materializedViews[].minGranularity` and

        `metadataMaterializedViews.granularity`) accept the same short format

        the API returns (e.g. `5m`, `15s`, `1h`, `1d`).

        '
      operationId: createSource
      tags:
      - Sources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
      responses:
        '200':
          description: Successfully created source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResponseEnvelope'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Body validation failed: name: Required'
        '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'
  /api/v2/sources/{id}:
    get:
      summary: Get Source
      description: Retrieves a specific source by ID
      operationId: getSource
      tags:
      - Sources
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Source ID
        example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: Successfully retrieved source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResponseEnvelope'
        '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'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Source not found
    put:
      summary: Update Source
      description: 'Updates an existing source. The full source object must be provided;

        this is a replace, not a patch.


        The request body is a source object without the `id` field. If an

        `id` is sent anyway it is silently ignored (stripped before

        validation — never a 400); the path parameter alone identifies the

        source. Granularity fields (`materializedViews[].minGranularity` and

        `metadataMaterializedViews.granularity`) accept the same short format

        the API returns (e.g. `5m`, `15s`, `1h`, `1d`).

        '
      operationId: updateSource
      tags:
      - Sources
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Source ID
        example: 507f1f77bcf86cd799439011
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Source'
      responses:
        '200':
          description: Successfully updated source
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SourceResponseEnvelope'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: 'Body validation failed: name: Required'
        '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'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Source not found
    delete:
      summary: Delete Source
      description: Deletes a source
      operationId: deleteSource
      tags:
      - Sources
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Source ID
        example: 507f1f77bcf86cd799439011
      responses:
        '200':
          description: Successfully deleted source
          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.
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                message: Source not found
components:
  schemas:
    MaterializedView:
      type: object
      required:
      - databaseName
      - tableName
      - dimensionColumns
      - minGranularity
      - timestampColumn
      - aggregatedColumns
      properties:
        databaseName:
          type: string
          description: Database name for the materialized view
          example: otel
        tableName:
          type: string
          description: Table name for the materialized view
          example: otel_logs_mv_5m
        dimensionColumns:
          type: string
          description: Columns which are not pre-aggregated in the materialized view and can be used for filtering and grouping.
          example: ServiceName, SeverityText
        minGranularity:
          type: string
          description: 'The granularity of the timestamp column: a positive integer followed by a unit (s, m, h, d). Common values: 1s, 15s, 30s, 1m, 5m, 15m, 30m, 1h, 2h, 6h, 12h, 1d, 2d, 7d, 30d.'
          pattern: ^\d+(s|m|h|d)$
          example: 5m
        minDate:
          type:
          - string
          - 'null'
          format: date-time
          description: (Optional) The earliest date and time for which the materialized view contains data. If not provided, then HyperDX will assume that the materialized view contains data for all dates for which the source table contains data.
          example: '2025-01-01T00:00:00Z'
        timestampColumn:
          type: string
          description: Timestamp column name
          example: Timestamp
        aggregatedColumns:
          type: array
          description: Columns which are pre-aggregated by the materialized view
          items:
            $ref: '#/components/schemas/AggregatedColumn'
    MetricTables:
      type: object
      description: Mapping of metric data types to table names. At least one must be specified.
      properties:
        gauge:
          type: string
          description: Table containing gauge metrics data
          example: otel_metrics_gauge
        histogram:
          type: string
          description: Table containing histogram metrics data
          example: otel_metrics_histogram
        sum:
          type: string
          description: Table containing sum metrics data
          example: otel_metrics_sum
        summary:
          type: string
          description: Table containing summary metrics data. Note - not yet fully supported by HyperDX
          example: otel_metrics_summary
        exponential histogram:
          type: string
          description: Table containing exponential histogram metrics data. Note - not yet fully supported by HyperDX
          example: otel_metrics_exponential_histogram
    MetricSourceFrom:
      type: object
      required:
      - databaseName
      properties:
        databaseName:
          type: string
          description: ClickHouse database name
          example: otel
        tableName:
          type:
          - string
          - 'null'
          description: ClickHouse table name
          example: otel_metrics_gauge
    Source:
      oneOf:
      - $ref: '#/components/schemas/LogSource'
      - $ref: '#/components/schemas/TraceSource'
      - $ref: '#/components/schemas/MetricSource'
      - $ref: '#/components/schemas/SessionSource'
      - $ref: '#/components/schemas/PromqlSource'
      discriminator:
        propertyName: kind
        mapping:
          log: '#/components/schemas/LogSource'
          trace: '#/components/schemas/TraceSource'
          metric: '#/components/schemas/MetricSource'
          session: '#/components/schemas/SessionSource'
          promql: '#/components/schemas/PromqlSource'
    SessionSource:
      type: object
      required:
      - name
      - kind
      - connection
      - from
      - traceSourceId
      properties:
        id:
          type: string
          readOnly: true
          description: Unique source ID. Server-generated; ignored if sent in create/update requests.
          example: 507f1f77bcf86cd799439031
        name:
          type: string
          description: Display name for the source.
          example: Sessions
        section:
          type: string
          maxLength: 256
          description: Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type:
          - boolean
          - 'null'
          description: When true, the source is hidden from source selectors in the UI. Defaults to false.
          example: false
        kind:
          type: string
          enum:
          - session
          description: Source kind discriminator. Must be "session" for session sources.
          example: session
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type:
          - array
          - 'null'
          description: Optional ClickHouse query settings applied when querying this source.
          items:
            $ref: '#/components/schemas/QuerySetting'
        timestampValueExpression:
          type:
          - string
          - 'null'
          description: DateTime column or expression that is part of your table's primary key.
          example: TimestampTime
        traceSourceId:
          type: string
          description: HyperDX Source for traces associated with sessions.
          example: 507f1f77bcf86cd799439021
    SourceFrom:
      type: object
      required:
      - databaseName
      - tableName
      properties:
        databaseName:
          type: string
          description: ClickHouse database name
          example: otel
        tableName:
          type: string
          description: ClickHouse table name
          example: otel_logs
    HighlightedAttributeExpression:
      type: object
      required:
      - sqlExpression
      properties:
        sqlExpression:
          type: string
          description: SQL expression for the attribute
          example: SpanAttributes['http.status_code']
        luceneExpression:
          type:
          - string
          - 'null'
          description: An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.
          example: http.status_code
        alias:
          type:
          - string
          - 'null'
          description: Optional alias for the attribute
          example: HTTP Status Code
    MetricSource:
      type: object
      required:
      - name
      - kind
      - connection
      - from
      - metricTables
      - timestampValueExpression
      - resourceAttributesExpression
      properties:
        id:
          type: string
          readOnly: true
          description: Unique source ID. Server-generated; ignored if sent in create/update requests.
          example: 507f1f77bcf86cd799439041
        name:
          type: string
          description: Display name for the source.
          example: Metrics
        section:
          type: string
          maxLength: 256
          description: Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type:
          - boolean
          - 'null'
          description: When true, the source is hidden from source selectors in the UI. Defaults to false.
          example: false
        kind:
          type: string
          enum:
          - metric
          description: Source kind discriminator. Must be "metric" for metric sources.
          example: metric
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/MetricSourceFrom'
          description: Database and optional table location of the metric source data.
        querySettings:
          type:
          - array
          - 'null'
          description: Optional ClickHouse query settings applied when querying this source.
          items:
            $ref: '#/components/schemas/QuerySetting'
        metricTables:
          $ref: '#/components/schemas/MetricTables'
          description: Mapping of metric data types to their respective table names.
        timestampValueExpression:
          type: string
          description: DateTime column or expression that is part of your table's primary key.
          example: TimeUnix
        resourceAttributesExpression:
          type: string
          description: Column containing resource attributes for metrics
          example: ResourceAttributes
        logSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for logs associated with metrics. Optional
          example: 507f1f77bcf86cd799439011
    AggregatedColumn:
      type: object
      required:
      - mvColumn
      - aggFn
      properties:
        sourceColumn:
          type:
          - string
          - 'null'
          description: Source column name
          example: Duration
        aggFn:
          type: string
          description: Aggregation function (e.g., count, sum, avg)
          example: sum
        mvColumn:
          type: string
          description: Materialized view column name
          example: sum__Duration
    SourceResponseEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Source'
          description: The source object.
    TraceSource:
      type: object
      required:
      - name
      - kind
      - connection
      - from
      - defaultTableSelectExpression
      - timestampValueExpression
      - durationExpression
      - durationPrecision
      - traceIdExpression
      - spanIdExpression
      - parentSpanIdExpression
      - spanNameExpression
      - spanKindExpression
      properties:
        id:
          type: string
          readOnly: true
          description: Unique source ID. Server-generated; ignored if sent in create/update requests.
          example: 507f1f77bcf86cd799439021
        name:
          type: string
          description: Display name for the source.
          example: Traces
        section:
          type: string
          maxLength: 256
          description: Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type:
          - boolean
          - 'null'
          description: When true, the source is hidden from source selectors in the UI. Defaults to false.
          example: false
        kind:
          type: string
          enum:
          - trace
          description: Source kind discriminator. Must be "trace" for trace sources.
          example: trace
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type:
          - array
          - 'null'
          description: Optional ClickHouse query settings applied when querying this source.
          items:
            $ref: '#/components/schemas/QuerySetting'
        defaultTableSelectExpression:
          type: string
          description: Default columns selected in search results (this can be customized per search later)
          example: Timestamp, SpanName, ServiceName, Duration
        timestampValueExpression:
          type: string
          description: DateTime column or expression defines the start of the span
          example: Timestamp
        durationExpression:
          type: string
          description: Expression to extract span duration.
          example: Duration
        durationPrecision:
          type: integer
          minimum: 0
          maximum: 9
          default: 3
          description: Number of decimal digits in the duration value (e.g., 3 for milliseconds, 6 for microseconds, 9 for nanoseconds).
        traceIdExpression:
          type: string
          description: Expression to extract the trace ID.
          example: TraceId
        spanIdExpression:
          type: string
          description: Expression to extract the span ID.
          example: SpanId
        parentSpanIdExpression:
          type: string
          description: Expression to extract the parent span ID.
          example: ParentSpanId
        spanNameExpression:
          type: string
          description: Expression to extract the span name.
          example: SpanName
        spanKindExpression:
          type: string
          description: Expression to extract the span kind (e.g., client, server, internal).
          example: SpanKind
        logSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for logs associated with traces. Optional
          example: 507f1f77bcf86cd799439011
        sessionSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for sessions associated with traces. Optional
          example: 507f1f77bcf86cd799439031
        metricSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for metrics associated with traces. Optional
          example: 507f1f77bcf86cd799439041
        statusCodeExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the span status code.
          example: StatusCode
        statusMessageExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the span status message.
          example: StatusMessage
        serviceNameExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the service name from trace rows.
          example: ServiceName
        serviceVersionExpression:
          type:
          - string
          - 'null'
          description: Expression identifying the running release of a service. Defaults to the OpenTelemetry service.version resource attribute when unset. Where services carry the release on different attributes, fall back across them with coalesce(nullIf(a, ''), nullIf(b, '')).
          example: ResourceAttributes['service.version']
        resourceAttributesExpression:
          type:
          - string
          - 'null'
          description: Expression to extract resource-level attributes.
          example: ResourceAttributes
        eventAttributesExpression:
          type:
          - string
          - 'null'
          description: Expression to extract event-level attributes.
          example: SpanAttributes
        spanEventsValueExpression:
          type:
          - string
          - 'null'
          description: Expression to extract span events. Used to capture events associated with spans. Expected to be Nested ( Timestamp DateTime64(9), Name LowCardinality(String), Attributes Map(LowCardinality(String), String)
          example: Events
        implicitColumnExpression:
          type:
          - string
          - 'null'
          description: Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.
          example: SpanName
        knownColumnsListExpression:
          type:
          - string
          - 'null'
          description: For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.
          example: Timestamp, Body, ServiceName
        useTextIndexForImplicitColumn:
          type:
          - string
          - 'null'
          enum:
          - auto
          - enabled
          - disabled
          description: Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.
          example: auto
        highlightedTraceAttributeExpressions:
          type:
          - array
          - 'null'
          description: Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
        highlightedRowAttributeExpressions:
          type:
          - array
          - 'null'
          description: Expressions defining row-level attributes which are displayed in the row side panel for the selected row
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
        materializedViews:
          type:
          - array
          - 'null'
          description: Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.
          items:
            $ref: '#/components/schemas/MaterializedView'
        metadataMaterializedViews:
          type:
          - object
          - 'null'
          description: Configure materialized views for fast field discovery and value autocomplete.
          properties:
            keyRollupTable:
              type: string
              description: ClickHouse table name for the key rollup (field discovery).
              example: otel_traces_key_rollup_15m
            kvRollupTable:
              type: string
              description: ClickHouse table name for the key-value rollup (value autocomplete).
              example: otel_traces_kv_rollup_15m
            granularity:
              type: string
              description: The time granularity of the rollup tables.
              example: 15m
    LogSource:
      type: object
      required:
      - name
      - kind
      - connection
      - from
      - defaultTableSelectExpression
      - timestampValueExpression
      properties:
        id:
          type: string
          readOnly: true
          description: Unique source ID. Server-generated; ignored if sent in create/update requests.
          example: 507f1f77bcf86cd799439011
        name:
          type: string
          description: Display name for the source.
          example: Logs
        section:
          type: string
          maxLength: 256
          description: Optional grouping label used to organize sources in the source selector. Sources that share a section value are displayed together.
          example: Billing
        disabled:
          type:
          - boolean
          - 'null'
          description: When true, the source is hidden from source selectors in the UI. Defaults to false.
          example: false
        kind:
          type: string
          enum:
          - log
          description: Source kind discriminator. Must be "log" for log sources.
          example: log
        connection:
          type: string
          description: ID of the ClickHouse connection used by this source.
          example: 507f1f77bcf86cd799439012
        from:
          $ref: '#/components/schemas/SourceFrom'
          description: Database and table location of the source data.
        querySettings:
          type:
          - array
          - 'null'
          description: Optional ClickHouse query settings applied when querying this source.
          items:
            $ref: '#/components/schemas/QuerySetting'
        defaultTableSelectExpression:
          type: string
          description: Default columns selected in search results (this can be customized per search later)
          example: Timestamp, ServiceName, SeverityText, Body
        timestampValueExpression:
          type: string
          description: DateTime column or expression that is part of your table's primary key.
          example: Timestamp
        serviceNameExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the service name from log rows.
          example: ServiceName
        serviceVersionExpression:
          type:
          - string
          - 'null'
          description: Expression identifying the running release of a service. Defaults to the OpenTelemetry service.version resource attribute when unset. Where services carry the release on different attributes, fall back across them with coalesce(nullIf(a, ''), nullIf(b, '')).
          example: ResourceAttributes['service.version']
        severityTextExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the severity/log level text.
          example: SeverityText
        bodyExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the log message body.
          example: Body
        eventAttributesExpression:
          type:
          - string
          - 'null'
          description: Expression to extract event-level attributes.
          example: LogAttributes
        resourceAttributesExpression:
          type:
          - string
          - 'null'
          description: Expression to extract resource-level attributes.
          example: ResourceAttributes
        displayedTimestampValueExpression:
          type:
          - string
          - 'null'
          description: This DateTime column is used to display and order search results.
          example: TimestampTime
        metricSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for metrics associated with logs. Optional
          example: 507f1f77bcf86cd799439013
        traceSourceId:
          type:
          - string
          - 'null'
          description: HyperDX Source for traces associated with logs. Optional
          example: 507f1f77bcf86cd799439014
        traceIdExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the trace ID for correlating logs with traces.
          example: TraceId
        spanIdExpression:
          type:
          - string
          - 'null'
          description: Expression to extract the span ID for correlating logs with traces.
          example: SpanId
        implicitColumnExpression:
          type:
          - string
          - 'null'
          description: Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.
          example: Body
        knownColumnsListExpression:
          type:
          - string
          - 'null'
          description: For Distributed table sources whose target tables have non-matching column sets. A list of columns supported across all target tables, used instead of SELECT * when fetching full row data. Leave blank to select all columns.
          example: Timestamp, Body, ServiceName
        useTextIndexForImplicitColumn:
          type:
          - string
          - 'null'
          enum:
          - auto
          - enabled
          - disabled
          description: Controls whether lucene rendering uses ClickHouse text indices via hasAllTokens() against the implicit column. "auto" detects a covering index at query time, "enabled" forces text index usage, "disabled" forces a LIKE/hasToken fallback.
          example: auto
        highlightedTraceAttributeExpressions:
          type:
          - array
          - 'null'
          description: Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
        highlightedRowAttributeExpressions:
          type:
          - array
          - 'null'
          description: Expressions defining row-level attributes which are displayed in the row side panel for the selected row.
          items:
            $ref: '#/components/schemas/HighlightedAttributeExpression'
        materializedViews:
          type:
          - array
          - 'null'
          description: Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.
          items:
            $ref: '#/components/schemas/MaterializedView'
        metadataMaterializedViews:
          type:
          - object
          - 'null'
          description: Configure materialized views for fast field discovery and value autocomplete.
          properties:
            keyRollupTable:
             

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