Elgato_dark/hyperdx
1
0
Fork 0
mirror of https://github.com/hyperdxio/hyperdx synced 2026-04-21 13:37:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6
hyperdx/packages/api/openapi.json
Drew Davis d3a61f9bb9
feat: Add additional alert threshold types (#2122) 
## Summary

This PR adds new types of alert thresholds: >, <=, =, and !=.

### Screenshots or video

https://github.com/user-attachments/assets/159bffc4-87e5-41af-b59b-51d4bc88d6ed

### How to test locally or on Vercel

This must be tested locally, since alerts are not supported in the preview environment.

To see the notification content, run an echo server locally and create a webhook that targets it (http://localhost:3000):

```bash
npx http-echo-server
```

### References



- Linear Issue: Closes HDX-3988
- Related PRs:
2026-04-16 15:47:04 +00:00

4478 lines
No EOL
142 KiB
JSON
Raw Blame History

{
"openapi": "3.0.0",
"info": {
"title": "HyperDX External API",
"description": "API for managing HyperDX alerts and dashboards",
"version": "2.0.0"
},
"servers": [
{
"url": "/",
"description": "Your HyperDX instance (http://<host>:<port>)"
}
],
"tags": [
{
"name": "Dashboards",
"description": "Endpoints for managing dashboards and their visualizations"
},
{
"name": "Alerts",
"description": "Endpoints for managing monitoring alerts"
},
{
"name": "Charts",
"description": "Endpoints for querying chart data"
},
{
"name": "Sources",
"description": "Endpoints for managing data sources"
},
{
"name": "Webhooks",
"description": "Endpoints for managing webhooks"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "API Key"
}
},
"schemas": {
"Error": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Human-readable error message.",
"example": "NOT_FOUND: Alert not found"
}
}
},
"AlertInterval": {
"type": "string",
"enum": [
"1m",
"5m",
"15m",
"30m",
"1h",
"6h",
"12h",
"1d"
],
"description": "Evaluation interval."
},
"AlertThresholdType": {
"type": "string",
"enum": [
"above",
"below",
"above_exclusive",
"below_or_equal",
"equal",
"not_equal"
],
"description": "Threshold comparison direction."
},
"AlertSource": {
"type": "string",
"enum": [
"saved_search",
"tile"
],
"description": "Alert source type."
},
"AlertState": {
"type": "string",
"enum": [
"ALERT",
"OK",
"INSUFFICIENT_DATA",
"DISABLED"
],
"description": "Current alert state."
},
"AlertChannelType": {
"type": "string",
"enum": [
"webhook"
],
"description": "Channel type."
},
"AlertSilenced": {
"type": "object",
"description": "Silencing metadata.",
"properties": {
"by": {
"type": "string",
"description": "User ID who silenced the alert.",
"nullable": true,
"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"
}
}
},
"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"
}
}
},
"AlertChannel": {
"oneOf": [
{
"$ref": "#/components/schemas/AlertChannelWebhook"
}
],
"discriminator": {
"propertyName": "type"
}
},
"Alert": {
"type": "object",
"properties": {
"dashboardId": {
"type": "string",
"description": "Dashboard ID for tile-based alerts.",
"nullable": true,
"example": "65f5e4a3b9e77c001a567890"
},
"tileId": {
"type": "string",
"description": "Tile ID for tile-based alerts. Must be a line, stacked bar, or number type tile.",
"nullable": true,
"example": "65f5e4a3b9e77c001a901234"
},
"savedSearchId": {
"type": "string",
"description": "Saved search ID for saved_search alerts.",
"nullable": true,
"example": "65f5e4a3b9e77c001a345678"
},
"groupBy": {
"type": "string",
"description": "Group-by key for saved search alerts.",
"nullable": true,
"example": "ServiceName"
},
"threshold": {
"type": "number",
"description": "Threshold value for triggering the alert.",
"example": 100
},
"interval": {
"$ref": "#/components/schemas/AlertInterval",
"description": "Evaluation interval for the alert.",
"example": "1h"
},
"scheduleOffsetMinutes": {
"type": "integer",
"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).",
"nullable": true,
"example": 2
},
"scheduleStartAt": {
"type": "string",
"format": "date-time",
"description": "Absolute UTC start time anchor. Alert windows start from this timestamp and repeat every interval.",
"nullable": true,
"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": "Alert notification channel configuration."
},
"name": {
"type": "string",
"description": "Human-friendly alert name.",
"nullable": true,
"example": "Test Alert"
},
"message": {
"type": "string",
"description": "Alert message template.",
"nullable": true,
"example": "Test Alert Message"
}
}
},
"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.",
"nullable": true
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Creation timestamp.",
"example": "2023-01-01T00:00:00.000Z"
},
"updatedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Last update timestamp.",
"example": "2023-01-01T00:00:00.000Z"
}
}
}
]
},
"CreateAlertRequest": {
"allOf": [
{
"$ref": "#/components/schemas/Alert"
},
{
"type": "object",
"required": [
"threshold",
"interval",
"thresholdType",
"channel"
]
}
]
},
"UpdateAlertRequest": {
"allOf": [
{
"$ref": "#/components/schemas/Alert"
},
{
"type": "object",
"required": [
"threshold",
"interval",
"thresholdType",
"channel"
]
}
]
},
"AlertResponseEnvelope": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/AlertResponse",
"description": "The alert object."
}
}
},
"AlertsListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "List of alert objects.",
"items": {
"$ref": "#/components/schemas/AlertResponse"
}
}
}
},
"EmptyResponse": {
"type": "object",
"properties": {}
},
"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"
}
}
},
"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"
}
}
},
"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"
]
}
}
},
"SeriesResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "Array of data points for the series",
"items": {
"$ref": "#/components/schemas/SeriesDataPoint"
}
}
}
},
"NumberFormatOutput": {
"type": "string",
"enum": [
"currency",
"percent",
"byte",
"time",
"number",
"data_rate",
"throughput"
],
"description": "Output format type (currency, percent, byte, time, number, data_rate, throughput)."
},
"AggregationFunction": {
"type": "string",
"enum": [
"avg",
"count",
"count_distinct",
"last_value",
"max",
"min",
"quantile",
"sum",
"any",
"none"
],
"description": "Aggregation function to apply to the field or metric value."
},
"QueryLanguage": {
"type": "string",
"enum": [
"sql",
"lucene"
],
"description": "Query language for the where clause."
},
"SavedFilterValue": {
"type": "object",
"required": [
"condition"
],
"properties": {
"type": {
"type": "string",
"enum": [
"sql"
],
"default": "sql",
"description": "Filter type. Currently only \"sql\" is supported.",
"example": "sql"
},
"condition": {
"type": "string",
"description": "SQL filter condition. For example use expressions in the form \"column IN ('value')\".",
"example": "ServiceName IN ('hdx-oss-dev-api')"
}
}
},
"MetricDataType": {
"type": "string",
"enum": [
"sum",
"gauge",
"histogram",
"summary",
"exponential histogram"
],
"description": "Metric data type, only for metrics data sources."
},
"TimeSeriesDisplayType": {
"type": "string",
"enum": [
"stacked_bar",
"line"
],
"description": "Visual representation type for the time series."
},
"QuantileLevel": {
"type": "number",
"enum": [
0.5,
0.9,
0.95,
0.99
],
"description": "Percentile level; only valid when aggFn is \"quantile\"."
},
"SortOrder": {
"type": "string",
"enum": [
"desc",
"asc"
],
"description": "Sort order for table rows."
},
"NumberFormat": {
"type": "object",
"properties": {
"output": {
"$ref": "#/components/schemas/NumberFormatOutput",
"description": "Output format applied to the number.",
"example": "number"
},
"mantissa": {
"type": "integer",
"description": "Number of decimal places.",
"example": 2
},
"thousandSeparated": {
"type": "boolean",
"description": "Whether to use thousand separators.",
"example": true
},
"average": {
"type": "boolean",
"description": "Whether to show as average.",
"example": false
},
"decimalBytes": {
"type": "boolean",
"description": "Use decimal bytes (1000) vs binary bytes (1024).",
"example": false
},
"factor": {
"type": "number",
"description": "Multiplication factor.",
"example": 1
},
"currencySymbol": {
"type": "string",
"description": "Currency symbol for currency format.",
"example": "$"
},
"numericUnit": {
"type": "string",
"enum": [
"bytes_iec",
"bytes_si",
"bits_iec",
"bits_si",
"kibibytes",
"kilobytes",
"mebibytes",
"megabytes",
"gibibytes",
"gigabytes",
"tebibytes",
"terabytes",
"pebibytes",
"petabytes",
"packets_sec",
"bytes_sec_iec",
"bytes_sec_si",
"bits_sec_iec",
"bits_sec_si",
"kibibytes_sec",
"kibibits_sec",
"kilobytes_sec",
"kilobits_sec",
"mebibytes_sec",
"mebibits_sec",
"megabytes_sec",
"megabits_sec",
"gibibytes_sec",
"gibibits_sec",
"gigabytes_sec",
"gigabits_sec",
"tebibytes_sec",
"tebibits_sec",
"terabytes_sec",
"terabits_sec",
"pebibytes_sec",
"pebibits_sec",
"petabytes_sec",
"petabits_sec",
"cps",
"ops",
"rps",
"reads_sec",
"wps",
"iops",
"cpm",
"opm",
"rpm_reads",
"wpm"
],
"description": "Numeric unit for data, data rate, or throughput formats.",
"example": "bytes_iec"
},
"unit": {
"type": "string",
"description": "Custom unit label.",
"example": "ms"
}
}
},
"TimeChartSeries": {
"type": "object",
"required": [
"type",
"sourceId",
"aggFn",
"where",
"whereLanguage",
"groupBy"
],
"properties": {
"type": {
"type": "string",
"enum": [
"time"
],
"description": "Series type discriminator. Must be \"time\" for time-series charts.",
"example": "time"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query",
"example": "65f5e4a3b9e77c001a567890"
},
"aggFn": {
"$ref": "#/components/schemas/AggregationFunction",
"description": "Aggregation function to apply to the field or metric value",
"example": "count"
},
"level": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Percentile level for quantile aggregations (e.g., 0.95 for p95)",
"example": 0.95
},
"field": {
"type": "string",
"description": "Column or expression to aggregate (required for most aggregation functions except count)",
"example": "duration"
},
"alias": {
"type": "string",
"description": "Display name for the series in the chart",
"example": "Request Duration"
},
"where": {
"type": "string",
"description": "Filter query for the data (syntax depends on whereLanguage)",
"example": "service:api"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause",
"example": "lucene"
},
"groupBy": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Fields to group results by (creates separate series for each group)",
"example": [
"host"
]
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
},
"metricDataType": {
"$ref": "#/components/schemas/MetricDataType",
"description": "Metric data type, only for metrics data sources.",
"example": "sum"
},
"metricName": {
"type": "string",
"description": "Metric name for metrics data sources",
"example": "http.server.duration"
},
"displayType": {
"$ref": "#/components/schemas/TimeSeriesDisplayType",
"description": "Visual representation type for the time series",
"example": "line"
}
}
},
"TableChartSeries": {
"type": "object",
"required": [
"type",
"sourceId",
"aggFn",
"where",
"whereLanguage",
"groupBy"
],
"properties": {
"type": {
"type": "string",
"enum": [
"table"
],
"description": "Series type discriminator. Must be \"table\" for table charts.",
"example": "table"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query",
"example": "65f5e4a3b9e77c001a567890"
},
"aggFn": {
"$ref": "#/components/schemas/AggregationFunction",
"description": "Aggregation function to apply to the field or metric value",
"example": "count"
},
"level": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Percentile level for quantile aggregations (e.g., 0.95 for p95)",
"example": 0.95
},
"field": {
"type": "string",
"description": "Column or expression to aggregate (required for most aggregation functions except count)",
"example": "duration"
},
"alias": {
"type": "string",
"description": "Display name for the series",
"example": "Total Count"
},
"where": {
"type": "string",
"description": "Filter query for the data (syntax depends on whereLanguage)",
"example": "level:error"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause",
"example": "lucene"
},
"groupBy": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Fields to group results by (creates separate rows for each group)",
"example": [
"errorType"
]
},
"sortOrder": {
"$ref": "#/components/schemas/SortOrder",
"description": "Sort order for table rows",
"example": "desc"
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
},
"metricDataType": {
"$ref": "#/components/schemas/MetricDataType",
"description": "Metric data type, only for metrics data sources.",
"example": "sum"
},
"metricName": {
"type": "string",
"description": "Metric name for metrics data sources",
"example": "http.server.duration"
}
}
},
"NumberChartSeries": {
"type": "object",
"required": [
"type",
"sourceId",
"aggFn",
"where",
"whereLanguage"
],
"properties": {
"type": {
"type": "string",
"enum": [
"number"
],
"description": "Series type discriminator. Must be \"number\" for single-value number charts.",
"example": "number"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query",
"example": "65f5e4a3b9e77c001a567890"
},
"aggFn": {
"$ref": "#/components/schemas/AggregationFunction",
"description": "Aggregation function to apply to the field or metric value",
"example": "count"
},
"level": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Percentile level for quantile aggregations (e.g., 0.95 for p95)",
"example": 0.95
},
"field": {
"type": "string",
"description": "Column or expression to aggregate (required for most aggregation functions except count)",
"example": "duration"
},
"alias": {
"type": "string",
"description": "Display name for the series in the chart",
"example": "Total Requests"
},
"where": {
"type": "string",
"description": "Filter query for the data (syntax depends on whereLanguage)",
"example": "service:api"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause",
"example": "lucene"
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
},
"metricDataType": {
"$ref": "#/components/schemas/MetricDataType",
"description": "Metric data type, only for metrics data sources.",
"example": "sum"
},
"metricName": {
"type": "string",
"description": "Metric name for metrics data sources.",
"example": "http.server.duration"
}
}
},
"SearchChartSeries": {
"type": "object",
"required": [
"type",
"sourceId",
"fields",
"where",
"whereLanguage"
],
"properties": {
"type": {
"type": "string",
"enum": [
"search"
],
"description": "Series type discriminator. Must be \"search\" for search/log viewer charts.",
"example": "search"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query",
"example": "65f5e4a3b9e77c001a567890"
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of field names to display in the search results table",
"example": [
"timestamp",
"level",
"message"
]
},
"where": {
"type": "string",
"description": "Filter query for the data (syntax depends on whereLanguage)",
"example": "level:error"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause",
"example": "lucene"
}
}
},
"MarkdownChartSeries": {
"type": "object",
"required": [
"type",
"content"
],
"properties": {
"type": {
"type": "string",
"enum": [
"markdown"
],
"description": "Series type discriminator. Must be \"markdown\" for markdown text widgets.",
"example": "markdown"
},
"content": {
"type": "string",
"description": "Markdown content to render inside the widget.",
"example": "# Dashboard Title\n\nThis is a markdown widget.",
"maxLength": 100000
}
}
},
"DashboardChartSeries": {
"oneOf": [
{
"$ref": "#/components/schemas/TimeChartSeries"
},
{
"$ref": "#/components/schemas/TableChartSeries"
},
{
"$ref": "#/components/schemas/NumberChartSeries"
},
{
"$ref": "#/components/schemas/SearchChartSeries"
},
{
"$ref": "#/components/schemas/MarkdownChartSeries"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"time": "#/components/schemas/TimeChartSeries",
"table": "#/components/schemas/TableChartSeries",
"number": "#/components/schemas/NumberChartSeries",
"search": "#/components/schemas/SearchChartSeries",
"markdown": "#/components/schemas/MarkdownChartSeries"
}
}
},
"SelectItem": {
"type": "object",
"required": [
"aggFn"
],
"description": "A single aggregated value to compute. The valueExpression must be omitted when aggFn is \"count\", and required for all other functions. The level field may only be used with aggFn \"quantile\".\n",
"properties": {
"aggFn": {
"$ref": "#/components/schemas/AggregationFunction",
"description": "Aggregation function to apply. \"count\" does not require a valueExpression; \"quantile\" requires a level field indicating the desired percentile (e.g., 0.95).\n",
"example": "count"
},
"valueExpression": {
"type": "string",
"maxLength": 10000,
"description": "Expression for the column or value to aggregate. Must be omitted when aggFn is \"count\"; required for all other aggFn values.\n",
"example": "Duration"
},
"alias": {
"type": "string",
"maxLength": 10000,
"description": "Display alias for this select item in chart legends.",
"example": "Request Duration"
},
"level": {
"$ref": "#/components/schemas/QuantileLevel",
"description": "Percentile level; only valid when aggFn is \"quantile\"."
},
"where": {
"type": "string",
"maxLength": 10000,
"description": "SQL or Lucene filter condition applied before aggregation.",
"default": "",
"example": "service:api"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause."
},
"metricName": {
"type": "string",
"description": "Name of the metric to aggregate; only applicable when the source is a metrics source.",
"example": "http.server.duration"
},
"metricType": {
"$ref": "#/components/schemas/MetricDataType",
"description": "Metric type; only applicable when the source is a metrics source."
},
"periodAggFn": {
"type": "string",
"enum": [
"delta"
],
"description": "Optional period aggregation function for Gauge metrics (e.g., compute the delta over the period).",
"example": "delta"
}
}
},
"LineBuilderChartConfig": {
"type": "object",
"required": [
"displayType",
"sourceId",
"select"
],
"description": "Builder configuration for a line time-series chart.",
"properties": {
"displayType": {
"type": "string",
"enum": [
"line"
],
"description": "Display type discriminator. Must be \"line\" for line charts.",
"example": "line"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query.",
"example": "65f5e4a3b9e77c001a111111"
},
"select": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "One or more aggregated values to plot. When asRatio is true, exactly two select items are required.\n",
"items": {
"$ref": "#/components/schemas/SelectItem"
}
},
"groupBy": {
"type": "string",
"description": "Field expression to group results by (creates separate lines per group value).",
"example": "host",
"maxLength": 10000
},
"asRatio": {
"type": "boolean",
"description": "Plot select[0] / select[1] as a ratio. Requires exactly two select items.",
"default": false
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Expand date range boundaries to the query granularity interval.",
"default": true
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
},
"compareToPreviousPeriod": {
"type": "boolean",
"description": "Overlay the equivalent previous time period for comparison.",
"default": false
}
}
},
"BarBuilderChartConfig": {
"type": "object",
"required": [
"displayType",
"sourceId",
"select"
],
"description": "Builder configuration for a stacked-bar time-series chart.",
"properties": {
"displayType": {
"type": "string",
"enum": [
"stacked_bar"
],
"description": "Display type discriminator. Must be \"stacked_bar\" for stacked-bar charts.",
"example": "stacked_bar"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query.",
"example": "65f5e4a3b9e77c001a111111"
},
"select": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "One or more aggregated values to plot. When asRatio is true, exactly two select items are required.\n",
"items": {
"$ref": "#/components/schemas/SelectItem"
}
},
"groupBy": {
"type": "string",
"description": "Field expression to group results by (creates separate bars segments per group value).",
"example": "service",
"maxLength": 10000
},
"asRatio": {
"type": "boolean",
"description": "Plot select[0] / select[1] as a ratio. Requires exactly two select items.",
"default": false
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Align the date range boundaries to the query granularity interval.",
"default": true
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
}
}
},
"TableBuilderChartConfig": {
"type": "object",
"required": [
"displayType",
"sourceId",
"select"
],
"description": "Builder configuration for a table aggregation chart.",
"properties": {
"displayType": {
"type": "string",
"enum": [
"table"
],
"description": "Display type discriminator. Must be \"table\" for table charts.",
"example": "table"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query.",
"example": "65f5e4a3b9e77c001a111111"
},
"select": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"description": "One or more aggregated values to display as table columns. When asRatio is true, exactly two select items are required.\n",
"items": {
"$ref": "#/components/schemas/SelectItem"
}
},
"groupBy": {
"type": "string",
"maxLength": 10000,
"description": "Field expression to group results by (one row per group value).",
"example": "service"
},
"having": {
"type": "string",
"maxLength": 10000,
"description": "Post-aggregation SQL HAVING condition.",
"example": "count > 100"
},
"orderBy": {
"type": "string",
"maxLength": 10000,
"description": "SQL ORDER BY expression for sorting table rows.",
"example": "count DESC"
},
"asRatio": {
"type": "boolean",
"description": "Display select[0] / select[1] as a ratio. Requires exactly two select items.",
"example": false
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
}
}
},
"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": 1,
"description": "Exactly one aggregated value to display as a single number.",
"items": {
"$ref": "#/components/schemas/SelectItem"
}
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
}
}
},
"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"
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
}
}
},
"SearchChartConfig": {
"type": "object",
"required": [
"displayType",
"sourceId",
"select",
"whereLanguage"
],
"description": "Configuration for a raw-event search / log viewer tile.",
"properties": {
"displayType": {
"type": "string",
"enum": [
"search"
],
"description": "Display type discriminator. Must be \"search\" for search/log viewer tiles.",
"example": "search"
},
"sourceId": {
"type": "string",
"description": "ID of the data source to query.",
"example": "65f5e4a3b9e77c001a111111"
},
"select": {
"type": "string",
"maxLength": 10000,
"description": "Comma-separated list of expressions to display.",
"example": "timestamp, level, message"
},
"where": {
"type": "string",
"maxLength": 10000,
"description": "Filter condition for the search (syntax depends on whereLanguage).",
"default": "",
"example": "level:error"
},
"whereLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"description": "Query language for the where clause."
}
}
},
"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\n\nThis is a markdown widget."
}
}
},
"RawSqlChartConfigBase": {
"type": "object",
"required": [
"configType",
"connectionId",
"sqlTemplate"
],
"description": "Shared fields for Raw SQL chart configs. Set configType to \"sql\" and provide connectionId + sqlTemplate instead of sourceId + select.",
"properties": {
"configType": {
"type": "string",
"enum": [
"sql"
],
"description": "Must be \"sql\" to use the Raw SQL chart config variant.",
"example": "sql"
},
"connectionId": {
"type": "string",
"description": "ID of the ClickHouse connection to execute the query against.",
"example": "65f5e4a3b9e77c001a567890"
},
"sqlTemplate": {
"type": "string",
"maxLength": 100000,
"description": "SQL query template to execute. Supports HyperDX template variables.",
"example": "SELECT count() FROM otel_logs WHERE timestamp > now() - INTERVAL 1 HOUR"
},
"sourceId": {
"type": "string",
"description": "Optional ID of the data source associated with this Raw SQL chart. Used for applying dashboard filters.",
"example": "65f5e4a3b9e77c001a567890"
},
"numberFormat": {
"$ref": "#/components/schemas/NumberFormat",
"description": "Number formatting options for displayed values."
}
}
},
"LineRawSqlChartConfig": {
"description": "Raw SQL configuration for a line time-series chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"line"
],
"description": "Display as a line time-series chart.",
"example": "line"
},
"compareToPreviousPeriod": {
"type": "boolean",
"description": "Overlay the equivalent previous time period for comparison.",
"default": false
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Expand date range boundaries to the query granularity interval.",
"default": true
}
}
}
]
},
"BarRawSqlChartConfig": {
"description": "Raw SQL configuration for a stacked-bar time-series chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"stacked_bar"
],
"description": "Display as a stacked-bar time-series chart.",
"example": "stacked_bar"
},
"fillNulls": {
"type": "boolean",
"description": "Fill missing time buckets with zero instead of leaving gaps.",
"default": true
},
"alignDateRangeToGranularity": {
"type": "boolean",
"description": "Expand date range boundaries to the query granularity interval.",
"default": true
}
}
}
]
},
"TableRawSqlChartConfig": {
"description": "Raw SQL configuration for a table chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"table"
],
"description": "Display as a table chart.",
"example": "table"
}
}
}
]
},
"NumberRawSqlChartConfig": {
"description": "Raw SQL configuration for a single big-number chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"number"
],
"description": "Display as a single big-number chart.",
"example": "number"
}
}
}
]
},
"PieRawSqlChartConfig": {
"description": "Raw SQL configuration for a pie chart.",
"allOf": [
{
"$ref": "#/components/schemas/RawSqlChartConfigBase"
},
{
"type": "object",
"required": [
"displayType"
],
"properties": {
"displayType": {
"type": "string",
"enum": [
"pie"
],
"description": "Display as a pie chart.",
"example": "pie"
}
}
}
]
},
"LineChartConfig": {
"description": "Line chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n",
"oneOf": [
{
"$ref": "#/components/schemas/LineBuilderChartConfig"
},
{
"$ref": "#/components/schemas/LineRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/LineRawSqlChartConfig"
}
}
},
"BarChartConfig": {
"description": "Stacked-bar chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n",
"oneOf": [
{
"$ref": "#/components/schemas/BarBuilderChartConfig"
},
{
"$ref": "#/components/schemas/BarRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/BarRawSqlChartConfig"
}
}
},
"TableChartConfig": {
"description": "Table chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n",
"oneOf": [
{
"$ref": "#/components/schemas/TableBuilderChartConfig"
},
{
"$ref": "#/components/schemas/TableRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/TableRawSqlChartConfig"
}
}
},
"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).\n",
"oneOf": [
{
"$ref": "#/components/schemas/NumberBuilderChartConfig"
},
{
"$ref": "#/components/schemas/NumberRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/NumberRawSqlChartConfig"
}
}
},
"PieChartConfig": {
"description": "Pie chart. Omit configType for the builder variant (requires sourceId and select). Set configType to \"sql\" for the Raw SQL variant (requires connectionId and sqlTemplate).\n",
"oneOf": [
{
"$ref": "#/components/schemas/PieBuilderChartConfig"
},
{
"$ref": "#/components/schemas/PieRawSqlChartConfig"
}
],
"discriminator": {
"propertyName": "configType",
"mapping": {
"sql": "#/components/schemas/PieRawSqlChartConfig"
}
}
},
"TileConfig": {
"description": "Tile chart configuration. displayType is the primary discriminant and determines which variant group applies. For displayTypes that support both builder and Raw SQL modes (line, stacked_bar, table, number, pie), configType is the secondary discriminant: omit it for the builder variant or set it to \"sql\" for the Raw SQL variant. The search and markdown displayTypes only have a builder variant.\n",
"oneOf": [
{
"$ref": "#/components/schemas/LineChartConfig"
},
{
"$ref": "#/components/schemas/BarChartConfig"
},
{
"$ref": "#/components/schemas/TableChartConfig"
},
{
"$ref": "#/components/schemas/NumberChartConfig"
},
{
"$ref": "#/components/schemas/PieChartConfig"
},
{
"$ref": "#/components/schemas/SearchChartConfig"
},
{
"$ref": "#/components/schemas/MarkdownChartConfig"
}
],
"discriminator": {
"propertyName": "displayType",
"mapping": {
"line": "#/components/schemas/LineChartConfig",
"stacked_bar": "#/components/schemas/BarChartConfig",
"table": "#/components/schemas/TableChartConfig",
"number": "#/components/schemas/NumberChartConfig",
"pie": "#/components/schemas/PieChartConfig",
"search": "#/components/schemas/SearchChartConfig",
"markdown": "#/components/schemas/MarkdownChartConfig"
}
}
},
"TileBase": {
"type": "object",
"description": "Common fields shared by tile input and output",
"required": [
"name",
"x",
"y",
"w",
"h"
],
"properties": {
"name": {
"type": "string",
"description": "Display name for the tile",
"example": "Error Rate"
},
"x": {
"type": "integer",
"minimum": 0,
"maximum": 23,
"description": "Horizontal position in the grid (0-based)",
"example": 0
},
"y": {
"type": "integer",
"minimum": 0,
"description": "Vertical position in the grid (0-based)",
"example": 0
},
"w": {
"type": "integer",
"minimum": 1,
"maximum": 24,
"description": "Width in grid units",
"example": 6
},
"h": {
"type": "integer",
"minimum": 1,
"description": "Height in grid units",
"example": 3
},
"config": {
"$ref": "#/components/schemas/TileConfig",
"description": "Chart configuration for the tile. The displayType field determines which variant is used. Replaces the deprecated \"series\" and \"asRatio\" fields."
}
}
},
"TileOutput": {
"description": "Response format for dashboard tiles",
"allOf": [
{
"$ref": "#/components/schemas/TileBase"
},
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 36,
"description": "Unique tile ID assigned by the server.",
"example": "65f5e4a3b9e77c001a901234"
}
}
}
]
},
"TileInput": {
"description": "Input / request format when creating or updating tiles. The id field is optional: on create it is ignored (the server always assigns a new ID); on update, a matching id is used to identify the existing tile to preserve — tiles whose id does not match an existing tile are assigned a new generated ID.\n",
"allOf": [
{
"$ref": "#/components/schemas/TileBase"
},
{
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 36,
"description": "Optional tile ID. Omit to generate a new ID.",
"example": "65f5e4a3b9e77c001a901234"
},
"asRatio": {
"type": "boolean",
"description": "Display two series as a ratio (series[0] / series[1]). Only applicable when providing \"series\". Deprecated in favor of \"config.asRatio\".",
"example": false,
"deprecated": true
},
"series": {
"type": "array",
"minItems": 1,
"description": "Data series to display in this tile (all must be the same type). Deprecated; use \"config\" instead.",
"deprecated": true,
"items": {
"$ref": "#/components/schemas/DashboardChartSeries"
}
}
}
}
]
},
"FilterInput": {
"type": "object",
"description": "Dashboard filter key that can be added to a dashboard",
"required": [
"type",
"name",
"expression",
"sourceId"
],
"properties": {
"type": {
"type": "string",
"enum": [
"QUERY_EXPRESSION"
],
"description": "Filter type. Must be \"QUERY_EXPRESSION\".",
"example": "QUERY_EXPRESSION"
},
"name": {
"type": "string",
"minLength": 1,
"description": "Display name for the dashboard filter key",
"example": "Environment"
},
"expression": {
"type": "string",
"minLength": 1,
"description": "Key expression used when applying this dashboard filter key",
"example": "environment"
},
"sourceId": {
"type": "string",
"description": "Source ID this dashboard filter key applies to",
"example": "65f5e4a3b9e77c001a111111"
},
"sourceMetricType": {
"type": "string",
"enum": [
"sum",
"gauge",
"histogram",
"summary",
"exponential histogram"
],
"description": "Metric type when source is metrics",
"example": "gauge"
},
"where": {
"type": "string",
"description": "Optional WHERE condition to scope which rows this filter key reads values from",
"example": "ServiceName:api"
},
"whereLanguage": {
"type": "string",
"enum": [
"sql",
"lucene"
],
"description": "Language of the where condition",
"default": "sql",
"example": "lucene"
}
}
},
"Filter": {
"allOf": [
{
"$ref": "#/components/schemas/FilterInput"
},
{
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Unique dashboard filter key ID"
}
}
}
]
},
"Dashboard": {
"type": "object",
"description": "Dashboard with tiles and configuration",
"properties": {
"id": {
"type": "string",
"description": "Dashboard ID",
"example": "65f5e4a3b9e77c001a567890"
},
"name": {
"type": "string",
"description": "Dashboard name",
"maxLength": 1024,
"example": "Service Overview"
},
"tiles": {
"type": "array",
"description": "List of tiles/charts in the dashboard",
"items": {
"$ref": "#/components/schemas/TileOutput"
}
},
"tags": {
"type": "array",
"description": "Tags for organizing and filtering dashboards",
"items": {
"type": "string",
"maxLength": 32
},
"maxItems": 50,
"example": [
"production",
"monitoring"
]
},
"filters": {
"type": "array",
"description": "Dashboard filter keys added to the dashboard and applied to all tiles",
"items": {
"$ref": "#/components/schemas/Filter"
}
},
"savedQuery": {
"type": "string",
"nullable": true,
"description": "Optional default dashboard query restored when loading the dashboard.",
"example": "service.name = 'api'"
},
"savedQueryLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"nullable": true,
"description": "Query language used by savedQuery.",
"default": "lucene",
"example": "sql"
},
"savedFilterValues": {
"type": "array",
"description": "Optional default dashboard filter values restored when loading the dashboard.",
"items": {
"$ref": "#/components/schemas/SavedFilterValue"
}
}
}
},
"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.",
"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": "Dashboard filter keys to add to the dashboard and apply across all tiles",
"items": {
"$ref": "#/components/schemas/FilterInput"
}
},
"savedQuery": {
"type": "string",
"nullable": true,
"description": "Optional default dashboard query to persist on the dashboard.",
"example": "service.name = 'api'"
},
"savedQueryLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"nullable": true,
"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"
}
}
}
},
"UpdateDashboardRequest": {
"type": "object",
"required": [
"name",
"tiles"
],
"properties": {
"name": {
"type": "string",
"maxLength": 1024,
"description": "Dashboard name.",
"example": "Updated Dashboard Name"
},
"tiles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TileInput"
},
"description": "Full list of tiles for the dashboard. Existing tiles are matched by ID; tiles with an ID that does not match an existing tile will be assigned a new generated ID."
},
"tags": {
"type": "array",
"description": "Tags for organizing and filtering dashboards.",
"items": {
"type": "string",
"maxLength": 32
},
"maxItems": 50,
"example": [
"production",
"updated"
]
},
"filters": {
"type": "array",
"description": "Dashboard filter keys on the dashboard, applied across all tiles",
"items": {
"$ref": "#/components/schemas/Filter"
}
},
"savedQuery": {
"type": "string",
"nullable": true,
"description": "Optional default dashboard query to persist on the dashboard.",
"example": "service.name = 'api'"
},
"savedQueryLanguage": {
"$ref": "#/components/schemas/QueryLanguage",
"nullable": true,
"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"
}
}
}
},
"DashboardResponse": {
"allOf": [
{
"$ref": "#/components/schemas/Dashboard"
}
]
},
"DashboardResponseEnvelope": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/DashboardResponse",
"description": "The dashboard object."
}
}
},
"DashboardsListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "List of dashboard objects.",
"items": {
"$ref": "#/components/schemas/DashboardResponse"
}
}
}
},
"QuerySetting": {
"type": "object",
"required": [
"setting",
"value"
],
"properties": {
"setting": {
"type": "string",
"description": "ClickHouse setting name",
"example": "max_threads"
},
"value": {
"type": "string",
"description": "Setting value",
"example": "4"
}
}
},
"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"
}
}
},
"MetricSourceFrom": {
"type": "object",
"required": [
"databaseName"
],
"properties": {
"databaseName": {
"type": "string",
"description": "ClickHouse database name",
"example": "otel"
},
"tableName": {
"type": "string",
"description": "ClickHouse table name",
"nullable": true,
"example": "otel_metrics_gauge"
}
}
},
"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"
}
}
},
"HighlightedAttributeExpression": {
"type": "object",
"required": [
"sqlExpression"
],
"properties": {
"sqlExpression": {
"type": "string",
"description": "SQL expression for the attribute",
"example": "SpanAttributes['http.status_code']"
},
"luceneExpression": {
"type": "string",
"description": "An optional, Lucene version of the sqlExpression expression. If provided, it is used when searching for this attribute value.",
"nullable": true,
"example": "http.status_code"
},
"alias": {
"type": "string",
"description": "Optional alias for the attribute",
"nullable": true,
"example": "HTTP Status Code"
}
}
},
"AggregatedColumn": {
"type": "object",
"required": [
"mvColumn",
"aggFn"
],
"properties": {
"sourceColumn": {
"type": "string",
"description": "Source column name",
"nullable": true,
"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"
}
}
},
"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",
"enum": [
"1s",
"15s",
"30s",
"1m",
"5m",
"15m",
"30m",
"1h",
"2h",
"6h",
"12h",
"1d",
"2d",
"7d",
"30d"
],
"example": "5m"
},
"minDate": {
"type": "string",
"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.",
"nullable": true,
"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"
}
}
}
},
"LogSource": {
"type": "object",
"required": [
"id",
"name",
"kind",
"connection",
"from",
"defaultTableSelectExpression",
"timestampValueExpression"
],
"properties": {
"id": {
"type": "string",
"description": "Unique source ID.",
"example": "507f1f77bcf86cd799439011"
},
"name": {
"type": "string",
"description": "Display name for the source.",
"example": "Logs"
},
"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",
"description": "Optional ClickHouse query settings applied when querying this source.",
"items": {
"$ref": "#/components/schemas/QuerySetting"
},
"nullable": true
},
"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",
"description": "Expression to extract the service name from log rows.",
"nullable": true,
"example": "ServiceName"
},
"severityTextExpression": {
"type": "string",
"description": "Expression to extract the severity/log level text.",
"nullable": true,
"example": "SeverityText"
},
"bodyExpression": {
"type": "string",
"description": "Expression to extract the log message body.",
"nullable": true,
"example": "Body"
},
"eventAttributesExpression": {
"type": "string",
"description": "Expression to extract event-level attributes.",
"nullable": true,
"example": "LogAttributes"
},
"resourceAttributesExpression": {
"type": "string",
"description": "Expression to extract resource-level attributes.",
"nullable": true,
"example": "ResourceAttributes"
},
"displayedTimestampValueExpression": {
"type": "string",
"description": "This DateTime column is used to display and order search results.",
"nullable": true,
"example": "TimestampTime"
},
"metricSourceId": {
"type": "string",
"description": "HyperDX Source for metrics associated with logs. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439013"
},
"traceSourceId": {
"type": "string",
"description": "HyperDX Source for traces associated with logs. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439014"
},
"traceIdExpression": {
"type": "string",
"description": "Expression to extract the trace ID for correlating logs with traces.",
"nullable": true,
"example": "TraceId"
},
"spanIdExpression": {
"type": "string",
"description": "Expression to extract the span ID for correlating logs with traces.",
"nullable": true,
"example": "SpanId"
},
"implicitColumnExpression": {
"type": "string",
"description": "Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.",
"nullable": true,
"example": "Body"
},
"highlightedTraceAttributeExpressions": {
"type": "array",
"description": "Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.",
"items": {
"$ref": "#/components/schemas/HighlightedAttributeExpression"
},
"nullable": true
},
"highlightedRowAttributeExpressions": {
"type": "array",
"description": "Expressions defining row-level attributes which are displayed in the row side panel for the selected row.",
"items": {
"$ref": "#/components/schemas/HighlightedAttributeExpression"
},
"nullable": true
},
"materializedViews": {
"type": "array",
"description": "Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.",
"items": {
"$ref": "#/components/schemas/MaterializedView"
},
"nullable": true
}
}
},
"TraceSource": {
"type": "object",
"required": [
"id",
"name",
"kind",
"connection",
"from",
"timestampValueExpression",
"durationExpression",
"durationPrecision",
"traceIdExpression",
"spanIdExpression",
"parentSpanIdExpression",
"spanNameExpression",
"spanKindExpression"
],
"properties": {
"id": {
"type": "string",
"description": "Unique source ID.",
"example": "507f1f77bcf86cd799439021"
},
"name": {
"type": "string",
"description": "Display name for the source.",
"example": "Traces"
},
"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",
"description": "Optional ClickHouse query settings applied when querying this source.",
"items": {
"$ref": "#/components/schemas/QuerySetting"
},
"nullable": true
},
"defaultTableSelectExpression": {
"type": "string",
"description": "Default columns selected in search results (this can be customized per search later)",
"nullable": true,
"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",
"description": "HyperDX Source for logs associated with traces. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439011"
},
"sessionSourceId": {
"type": "string",
"description": "HyperDX Source for sessions associated with traces. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439031"
},
"metricSourceId": {
"type": "string",
"description": "HyperDX Source for metrics associated with traces. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439041"
},
"statusCodeExpression": {
"type": "string",
"description": "Expression to extract the span status code.",
"nullable": true,
"example": "StatusCode"
},
"statusMessageExpression": {
"type": "string",
"description": "Expression to extract the span status message.",
"nullable": true,
"example": "StatusMessage"
},
"serviceNameExpression": {
"type": "string",
"description": "Expression to extract the service name from trace rows.",
"nullable": true,
"example": "ServiceName"
},
"resourceAttributesExpression": {
"type": "string",
"description": "Expression to extract resource-level attributes.",
"nullable": true,
"example": "ResourceAttributes"
},
"eventAttributesExpression": {
"type": "string",
"description": "Expression to extract event-level attributes.",
"nullable": true,
"example": "SpanAttributes"
},
"spanEventsValueExpression": {
"type": "string",
"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)",
"nullable": true,
"example": "Events"
},
"implicitColumnExpression": {
"type": "string",
"description": "Column used for full text search if no property is specified in a Lucene-based search. Typically the message body of a log.",
"nullable": true,
"example": "SpanName"
},
"highlightedTraceAttributeExpressions": {
"type": "array",
"description": "Expressions defining trace-level attributes which are displayed in the trace view for the selected trace.",
"items": {
"$ref": "#/components/schemas/HighlightedAttributeExpression"
},
"nullable": true
},
"highlightedRowAttributeExpressions": {
"type": "array",
"description": "Expressions defining row-level attributes which are displayed in the row side panel for the selected row",
"items": {
"$ref": "#/components/schemas/HighlightedAttributeExpression"
},
"nullable": true
},
"materializedViews": {
"type": "array",
"description": "Configure materialized views for query optimization. These pre-aggregated views can significantly improve query performance on aggregation queries.",
"items": {
"$ref": "#/components/schemas/MaterializedView"
},
"nullable": true
}
}
},
"MetricSource": {
"type": "object",
"required": [
"id",
"name",
"kind",
"connection",
"from",
"metricTables",
"timestampValueExpression",
"resourceAttributesExpression"
],
"properties": {
"id": {
"type": "string",
"description": "Unique source ID.",
"example": "507f1f77bcf86cd799439041"
},
"name": {
"type": "string",
"description": "Display name for the source.",
"example": "Metrics"
},
"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",
"description": "Optional ClickHouse query settings applied when querying this source.",
"items": {
"$ref": "#/components/schemas/QuerySetting"
},
"nullable": true
},
"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",
"description": "HyperDX Source for logs associated with metrics. Optional",
"nullable": true,
"example": "507f1f77bcf86cd799439011"
}
}
},
"SessionSource": {
"type": "object",
"required": [
"id",
"name",
"kind",
"connection",
"from",
"traceSourceId"
],
"properties": {
"id": {
"type": "string",
"description": "Unique source ID.",
"example": "507f1f77bcf86cd799439031"
},
"name": {
"type": "string",
"description": "Display name for the source.",
"example": "Sessions"
},
"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",
"description": "Optional ClickHouse query settings applied when querying this source.",
"items": {
"$ref": "#/components/schemas/QuerySetting"
},
"nullable": true
},
"timestampValueExpression": {
"type": "string",
"description": "DateTime column or expression that is part of your table's primary key.",
"nullable": true,
"example": "TimestampTime"
},
"traceSourceId": {
"type": "string",
"description": "HyperDX Source for traces associated with sessions.",
"example": "507f1f77bcf86cd799439021"
}
}
},
"Source": {
"oneOf": [
{
"$ref": "#/components/schemas/LogSource"
},
{
"$ref": "#/components/schemas/TraceSource"
},
{
"$ref": "#/components/schemas/MetricSource"
},
{
"$ref": "#/components/schemas/SessionSource"
}
],
"discriminator": {
"propertyName": "kind",
"mapping": {
"log": "#/components/schemas/LogSource",
"trace": "#/components/schemas/TraceSource",
"metric": "#/components/schemas/MetricSource",
"session": "#/components/schemas/SessionSource"
}
}
},
"SourcesListResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "List of source objects.",
"items": {
"$ref": "#/components/schemas/Source"
}
}
}
},
"SlackWebhook": {
"type": "object",
"required": [
"id",
"name",
"service",
"updatedAt",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"description": "Webhook ID",
"example": "507f1f77bcf86cd799439011"
},
"name": {
"type": "string",
"description": "Webhook name",
"example": "Production Alerts"
},
"service": {
"type": "string",
"enum": [
"slack"
],
"description": "Webhook service type",
"example": "slack"
},
"url": {
"type": "string",
"description": "Slack incoming webhook URL",
"example": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
},
"description": {
"type": "string",
"description": "Webhook description, shown in the UI",
"example": "Sends critical alerts to the"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp",
"example": "2025-06-15T10:30:00.000Z"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp",
"example": "2025-01-01T00:00:00.000Z"
}
}
},
"IncidentIOWebhook": {
"type": "object",
"required": [
"id",
"name",
"service",
"updatedAt",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"description": "Webhook ID",
"example": "507f1f77bcf86cd799439012"
},
"name": {
"type": "string",
"description": "Webhook name",
"example": "Incident Response"
},
"service": {
"type": "string",
"enum": [
"incidentio"
],
"description": "Webhook service type",
"example": "incidentio"
},
"url": {
"type": "string",
"description": "incident.io alert event HTTP source URL",
"example": "https://api.incident.io/v2/alert_events/http/abc123"
},
"description": {
"type": "string",
"description": "Webhook description, shown in the UI",
"example": "Routes alerts to incident.io for on-call escalation"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp",
"example": "2025-06-15T10:30:00.000Z"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp",
"example": "2025-01-01T00:00:00.000Z"
}
}
},
"GenericWebhook": {
"type": "object",
"required": [
"id",
"name",
"service",
"updatedAt",
"createdAt"
],
"properties": {
"id": {
"type": "string",
"description": "Webhook ID",
"example": "507f1f77bcf86cd799439013"
},
"name": {
"type": "string",
"description": "Webhook name",
"example": "PagerDuty Integration"
},
"service": {
"type": "string",
"enum": [
"generic"
],
"description": "Webhook service type",
"example": "generic"
},
"url": {
"type": "string",
"description": "Webhook destination URL",
"example": "https://example.com/webhooks/alerts"
},
"description": {
"type": "string",
"description": "Webhook description, shown in the UI",
"example": "Forwards alert payloads to an external monitoring service"
},
"body": {
"type": "string",
"description": "Optional request body template",
"example": "{\"alert\": \"{{title}}\", \"severity\": \"{{level}}\"}"
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "Last update timestamp",
"example": "2025-06-15T10:30:00.000Z"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Creation timestamp",
"example": "2025-01-01T00:00:00.000Z"
}
}
},
"Webhook": {
"oneOf": [
{
"$ref": "#/components/schemas/SlackWebhook"
},
{
"$ref": "#/components/schemas/IncidentIOWebhook"
},
{
"$ref": "#/components/schemas/GenericWebhook"
}
],
"discriminator": {
"propertyName": "service",
"mapping": {
"slack": "#/components/schemas/SlackWebhook",
"incidentio": "#/components/schemas/IncidentIOWebhook",
"generic": "#/components/schemas/GenericWebhook"
}
}
},
"WebhooksListResponse": {
"type": "object",
"required": [
"data"
],
"properties": {
"data": {
"type": "array",
"description": "List of webhook objects.",
"items": {
"$ref": "#/components/schemas/Webhook"
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
],
"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",
"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"
}
}
}
},
"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"
}
}
}
},
"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"
}
}
}
},
"404": {
"description": "Alert not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/api/v2/alerts": {
"get": {
"summary": "List Alerts",
"description": "Retrieves a list of all alerts for the authenticated team",
"operationId": "listAlerts",
"tags": [
"Alerts"
],
"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"
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"message": "Unauthorized access. API key is missing or invalid."
}
}
}
}
}
},
"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"
}
}
}
}
}
},
"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"
}
}
}
},
"500": {
"description": "Server error or validation failure",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/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"
}
}
}
}
}
}
},
"/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",
"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/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"
}
}
}
}
}
}
},
"/api/v2/webhooks": {
"get": {
"summary": "List Webhooks",
"description": "Retrieves a list of all webhooks for the authenticated team",
"operationId": "listWebhooks",
"tags": [
"Webhooks"
],
"responses": {
"200": {
"description": "Successfully retrieved webhooks",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhooksListResponse"
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}
Reference in a new issue View git blame Copy permalink