{ "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://:)" } ], "tags": [ { "name": "Dashboards", "description": "Endpoints for managing dashboards and their visualizations" }, { "name": "Alerts", "description": "Endpoints for managing monitoring alerts" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key" } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" } } }, "AlertInterval": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "6h", "12h", "1d" ], "description": "Evaluation interval." }, "AlertThresholdType": { "type": "string", "enum": [ "above", "below" ], "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 }, "at": { "type": "string", "description": "Silence start timestamp.", "format": "date-time" }, "until": { "type": "string", "description": "Silence end timestamp.", "format": "date-time" } } }, "AlertChannelWebhook": { "type": "object", "required": [ "type", "webhookId" ], "properties": { "type": { "$ref": "#/components/schemas/AlertChannelType" }, "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.", "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", "example": "1h" }, "source": { "$ref": "#/components/schemas/AlertSource", "example": "tile" }, "thresholdType": { "$ref": "#/components/schemas/AlertThresholdType", "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", "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", "source", "thresholdType", "channel" ] } ] }, "UpdateAlertRequest": { "allOf": [ { "$ref": "#/components/schemas/Alert" }, { "type": "object", "required": [ "threshold", "interval", "source", "thresholdType", "channel" ] } ] }, "AlertResponseEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AlertResponse" } } }, "AlertsListResponse": { "type": "object", "properties": { "data": { "type": "array", "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", "items": { "$ref": "#/components/schemas/SeriesDataPoint" } } } }, "NumberFormatOutput": { "type": "string", "enum": [ "currency", "percent", "byte", "time", "number" ], "description": "Output format type (currency, percent, byte, time, number)." }, "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." }, "MetricDataType": { "type": "string", "enum": [ "sum", "gauge", "histogram", "summary", "exponential histogram" ], "description": "Metric data type for metrics data sources." }, "TimeSeriesDisplayType": { "type": "string", "enum": [ "stacked_bar", "line" ], "description": "Visual representation type for the time series." }, "SortOrder": { "type": "string", "enum": [ "desc", "asc" ], "description": "Sort order for table rows." }, "NumberFormat": { "type": "object", "properties": { "output": { "$ref": "#/components/schemas/NumberFormatOutput", "example": "number" }, "mantissa": { "type": "number", "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": "$" }, "unit": { "type": "string", "description": "Custom unit label.", "example": "ms" } } }, "TimeChartSeries": { "type": "object", "required": [ "type", "sourceId", "aggFn", "where", "groupBy" ], "properties": { "type": { "type": "string", "enum": [ "time" ], "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": "Field/property name 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" }, "metricDataType": { "$ref": "#/components/schemas/MetricDataType", "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", "groupBy" ], "properties": { "type": { "type": "string", "enum": [ "table" ], "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", "example": "duration" }, "alias": { "type": "string", "example": "Total Count" }, "where": { "type": "string", "example": "level:error" }, "whereLanguage": { "$ref": "#/components/schemas/QueryLanguage", "example": "lucene" }, "groupBy": { "type": "array", "items": { "type": "string" }, "maxItems": 10, "example": [ "errorType" ] }, "sortOrder": { "$ref": "#/components/schemas/SortOrder", "description": "Sort order for table rows", "example": "desc" }, "numberFormat": { "$ref": "#/components/schemas/NumberFormat" }, "metricDataType": { "$ref": "#/components/schemas/MetricDataType", "description": "Metric data type 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" ], "properties": { "type": { "type": "string", "enum": [ "number" ], "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", "example": "duration" }, "alias": { "type": "string", "example": "Total Requests" }, "where": { "type": "string", "example": "service:api" }, "whereLanguage": { "$ref": "#/components/schemas/QueryLanguage", "example": "lucene" }, "numberFormat": { "$ref": "#/components/schemas/NumberFormat" }, "metricDataType": { "$ref": "#/components/schemas/MetricDataType", "example": "sum" }, "metricName": { "type": "string", "example": "http.server.duration" } } }, "SearchChartSeries": { "type": "object", "required": [ "type", "sourceId", "fields", "where" ], "properties": { "type": { "type": "string", "enum": [ "search" ], "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" ], "example": "markdown" }, "content": { "type": "string", "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" } } }, "TileInput": { "type": "object", "description": "Dashboard tile/chart configuration for creation", "required": [ "name", "x", "y", "w", "h", "series" ], "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 }, "asRatio": { "type": "boolean", "description": "Display two series as a ratio (series[0] / series[1])", "example": false }, "series": { "type": "array", "minItems": 1, "description": "Data series to display in this tile (all must be the same type)", "items": { "$ref": "#/components/schemas/DashboardChartSeries" } } } }, "Tile": { "allOf": [ { "$ref": "#/components/schemas/TileInput" }, { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "maxLength": 36, "example": "65f5e4a3b9e77c001a901234" } } } ] }, "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/Tile" } }, "tags": { "type": "array", "description": "Tags for organizing and filtering dashboards", "items": { "type": "string", "maxLength": 32 }, "maxItems": 50, "example": [ "production", "monitoring" ] } } }, "CreateDashboardRequest": { "type": "object", "required": [ "name", "tiles" ], "properties": { "name": { "type": "string", "maxLength": 1024, "example": "New Dashboard" }, "tiles": { "type": "array", "items": { "$ref": "#/components/schemas/TileInput" } }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "maxItems": 50, "example": [ "development" ] } } }, "UpdateDashboardRequest": { "type": "object", "required": [ "name", "tiles" ], "properties": { "name": { "type": "string", "maxLength": 1024, "example": "Updated Dashboard Name" }, "tiles": { "type": "array", "items": { "$ref": "#/components/schemas/Tile" }, "description": "Tiles must include their IDs for updates. To add a new tile, generate a unique ID (max 36 chars)." }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 32 }, "maxItems": 50, "example": [ "production", "updated" ] } } }, "DashboardResponse": { "allOf": [ { "$ref": "#/components/schemas/Dashboard" } ] }, "DashboardResponseEnvelope": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DashboardResponse" } } }, "DashboardsListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DashboardResponse" } } } } } }, "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, "asRatio": false, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "avg", "field": "cpu.usage", "where": "host:server-01", "groupBy": [] } ] } ], "tags": [ "infrastructure", "monitoring" ] }, { "id": "65f5e4a3b9e77c001a567891", "name": "API Monitoring", "tiles": [ { "id": "65f5e4a3b9e77c001a901235", "name": "API Errors", "x": 0, "y": 0, "w": 6, "h": 3, "series": [ { "type": "table", "sourceId": "65f5e4a3b9e77c001a111112", "aggFn": "count", "where": "level:error", "groupBy": [ "service" ], "sortOrder": "desc" } ] } ], "tags": [ "api", "monitoring" ] } ] } } } } } }, "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 time series chart", "value": { "name": "API Monitoring Dashboard", "tiles": [ { "name": "API Request Volume", "x": 0, "y": 0, "w": 6, "h": 3, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "service:api", "groupBy": [] } ] } ], "tags": [ "api", "monitoring" ] } }, "complexDashboard": { "summary": "Dashboard with multiple chart types", "value": { "name": "Service Health Overview", "tiles": [ { "name": "Request Count", "x": 0, "y": 0, "w": 6, "h": 3, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "service:backend", "groupBy": [] } ] }, { "name": "Error Distribution", "x": 6, "y": 0, "w": 6, "h": 3, "series": [ { "type": "table", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "level:error", "groupBy": [ "errorType" ], "sortOrder": "desc" } ] } ], "tags": [ "service-health", "production" ] } } } } } }, "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, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "service:api", "groupBy": [] } ] } ], "tags": [ "api", "monitoring" ] } } } } } } }, "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, "asRatio": false, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "avg", "field": "cpu.usage", "where": "host:server-01", "groupBy": [] } ] }, { "id": "65f5e4a3b9e77c001a901235", "name": "Memory Usage", "x": 6, "y": 0, "w": 6, "h": 3, "asRatio": false, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "avg", "field": "memory.usage", "where": "host:server-01", "groupBy": [] } ] } ], "tags": [ "infrastructure", "monitoring" ] } } } } } } }, "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 Time Series Chart", "x": 0, "y": 0, "w": 6, "h": 3, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "level:error", "groupBy": [] } ] }, { "id": "new-tile-123", "name": "New Number Chart", "x": 6, "y": 0, "w": 6, "h": 3, "series": [ { "type": "number", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "level:info" } ] } ], "tags": [ "production", "updated" ] } } } } } }, "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 Time Series Chart", "x": 0, "y": 0, "w": 6, "h": 3, "series": [ { "type": "time", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "level:error", "groupBy": [] } ] }, { "id": "new-tile-123", "name": "New Number Chart", "x": 6, "y": 0, "w": 6, "h": 3, "series": [ { "type": "number", "sourceId": "65f5e4a3b9e77c001a111111", "aggFn": "count", "where": "level:info" } ] } ], "tags": [ "production", "updated" ] } } } } } } }, "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" } } } } } } } } }