--- title: "Create dashboard" method: POST path: "/dashboards" tags: ["dashboards"] --- # Create dashboard `POST /dashboards` ## Request - Base URL: `https://api.axiom.co/v2` - URL: `https://api.axiom.co/v2/dashboards` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a dashboard and generates a `uid` if you don't set one. If a dashboard with the `uid` already exists, updates it and returns `200`, which requires the current `version` or `overwrite: true`. ## Request body - DashboardUpsertRequest - `dashboard` DashboardDocument, required - `name` string, required - `owner` string, required: User ID of the dashboard owner. Use `X-AXIOM-EVERYONE` to make the dashboard accessible to all users in the organization. - `description` string - `charts` Chart[], required - union - TimeSeriesChart - `id` string, required - `sectionId` string, uuid - `type` 'TimeSeries', required - `name` string - `query` union, required - TimeSeriesNonMetricsAplQuery - … - TimeSeriesNativeMplQuery - … - HeatmapChart - `id` string, required - `sectionId` string, uuid - `type` 'Heatmap', required - `name` string - `query` union, required - HeatmapNonMetricsAplQuery - … - HeatmapNativeMplQuery - … - `colorScheme` 'Blue' | 'Orange' | 'Red' | 'Purple' | 'Teal' | 'Yellow' | 'Green' | 'Pink' | 'Grey' | 'Brown' - LogStreamChart - `id` string, required - `sectionId` string, uuid - `type` 'LogStream', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - `tableSettings` TableSettings - `columns` ColumnSetting[] - … - `settings` DatasetStreamSettings - … - PieChart - `id` string, required - `sectionId` string, uuid - `type` 'Pie', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - ScatterChart - `id` string, required - `sectionId` string, uuid - `type` 'Scatter', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - TableChart - `id` string, required - `sectionId` string, uuid - `type` 'Table', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - `tableSettings` TableSettings - `columns` ColumnSetting[] - … - `settings` DatasetStreamSettings - … - TopKChart - `id` string, required - `sectionId` string, uuid - `type` 'TopK', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - StatisticChart - `id` string, required - `sectionId` string, uuid - `type` 'Statistic', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - `colorScheme` 'Blue' | 'Orange' | 'Red' | 'Purple' | 'Teal' | 'Yellow' | 'Green' | 'Pink' | 'Grey' | 'Brown' - `customUnits` string - `showChart` union - boolean - string - `hideValue` boolean - `chartHeight` union - string - number - `errorThreshold` 'Above' | 'AboveOrEqual' | 'Below' | 'BelowOrEqual' | 'AboveOrBelow' - `errorThresholdValue` string - `warningThreshold` 'Above' | 'AboveOrEqual' | 'Below' | 'BelowOrEqual' | 'AboveOrBelow' - `warningThresholdValue` string - `roundTo` integer - `invertTheme` boolean - `background` string - `textColor` string - `labelColor` string - `chartFillColor` string - `okColorProps` StatisticChartColorProps - `background` string - `chartFillColor` string - `labelColor` string - `textColor` string - `warningColorProps` StatisticChartColorProps - `background` string - `chartFillColor` string - `labelColor` string - `textColor` string - `errorColorProps` StatisticChartColorProps - `background` string - `chartFillColor` string - `labelColor` string - `textColor` string - GaugeChart - `id` string, required - `sectionId` string, uuid - `type` 'Gauge', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - `segments` GaugeChartSegment[], required - `from` number, required - `to` number, required - `colorScale` 'green-to-red' | 'red-to-green' - `showRing` boolean - `labelMode` 'none' | 'boundaries' | 'intervals' - `showSparkline` boolean - `scaleToTimeRange` boolean - `scaleBaseDurationMs` number - `customUnits` string - NoteChart - `id` string, required - `sectionId` string, uuid - `type` 'Note', required - `text` string, required - `variant` '' | 'default' | 'plain', nullable - MonitorListChart - `id` string, required - `sectionId` string, uuid - `type` 'MonitorList', required - `name` string - `selectedMonitors` string[], required - `columns` MonitorListColumns, required - `status` boolean, required - `history` boolean, required - `dataset` boolean, required - `type` boolean, required - `notifiers` boolean, required - SmartFilterChart - `id` string, required - `sectionId` string, uuid - `type` 'SmartFilter', required - `name` string - `filters` SmartFilterConfig[], required - union - … - `logo` string - `logoDark` string - SpacerChart - `id` string, required - `sectionId` string, uuid - `type` 'Spacer', required - `name` string - `variant` 'transparent' | 'dashed' | 'solid' - VisualizeChart - `id` string, required - `sectionId` string, uuid - `type` 'Visualize', required - `name` string - `query` union, required - SimpleNonMetricsAplQuery - … - SimpleNativeMplQuery - … - `visualization` union, required - ScatterVisualization - … - BarVisualization - … - HorizontalBarVisualization - … - HistogramVisualization - … - FrequencyBarVisualization - … - VisualizeHeatmap - … - `layout` LayoutItem[], required - `i` string, required - `x` integer, required - `y` number, nullable, required - `w` integer, required - `h` number, required - `minW` integer - `minH` number - `maxW` integer - `maxH` integer - `static` boolean - `sections` Section[] - `id` string, uuid, required - `title` string, required - `defaultCollapsed` boolean - `refreshTime` 0 | 15 | 60 | 300, required - `schemaVersion` 2, required - `against` '-1h' | '-3h' | '-6h' | '-12h' | '-1d' | '-3d' | '-7d' | '-1w' | '-2w' | '-3w' | '-30d' | '-60d' | '-90d': Relative time comparison offset. Compares the current time window against a previous period offset by this duration. Mutually exclusive with `againstTimestamp` — setting one clears the other. Use an empty string or omit to disable comparison. - `againstTimestamp` string: A datetime value. Accepts ISO 8601 (e.g. `2024-01-02T00:00:00.000Z`), relative time using `now-{duration}` where duration is a number followed by `s` (seconds), `m` (minutes), `h` (hours), `d` (days), or `w` (weeks) (e.g. `now-1h`, `now-7d`), a Unix epoch millisecond timestamp as a string (e.g. `1704067200000`), or an empty string to clear the value. - `timeWindowStart` string, required: Start of the dashboard time range. Use `qr-now-{duration}` for a quick range relative to now, where duration is a number followed by `s` (seconds), `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). Examples: `qr-now-5m`, `qr-now-1h`, `qr-now-7d`. Alternatively, use a Unix epoch millisecond timestamp as a string (e.g. `1704067200000`). - `timeWindowEnd` string, required: End of the dashboard time range. Use `qr-now` for a rolling window that tracks the current time (pair with a `qr-now-{duration}` start), or a Unix epoch millisecond timestamp as a string (e.g. `1704153600000`). - `uid` string: Optional dashboard UID. Must contain only letters, numbers, underscores, or hyphens, with length 1-128 when provided. - `labelIds` LabelID[]: Existing label IDs; replaces assignments when supplied, clears with [], and preserves them when omitted or null. - `message` string - `overwrite` boolean - `uid` string: Stable external dashboard identifier (org-scoped unique). - `version` integer: Required for updates when overwrite is false. ## Response `200` Updated dashboard - DashboardWriteResponse - `dashboard` DashboardResource, required - `createdAt` string, date-time, nullable: Creation time, present only for managed dashboards. - `createdBy` string, nullable: Creator, present only for managed dashboards. - `dashboard` DashboardDocument, required - `name` string, required - `owner` string, required: User ID of the dashboard owner. Use `X-AXIOM-EVERYONE` to make the dashboard accessible to all users in the organization. - `description` string - `charts` Chart[], required - union - TimeSeriesChart - `id` string, required - `sectionId` string, uuid - `type` 'TimeSeries', required - `name` string - `query` union, required - … - HeatmapChart - `id` string, required - `sectionId` string, uuid - `type` 'Heatmap', required - `name` string - `query` union, required - … - `colorScheme` 'Blue' | 'Orange' | 'Red' | 'Purple' | 'Teal' | 'Yellow' | 'Green' | 'Pink' | 'Grey' | 'Brown' - LogStreamChart - `id` string, required - `sectionId` string, uuid - `type` 'LogStream', required - `name` string - `query` union, required - … - `tableSettings` TableSettings - … - PieChart - `id` string, required - `sectionId` string, uuid - `type` 'Pie', required - `name` string - `query` union, required - … - ScatterChart - `id` string, required - `sectionId` string, uuid - `type` 'Scatter', required - `name` string - `query` union, required - … - TableChart - `id` string, required - `sectionId` string, uuid - `type` 'Table', required - `name` string - `query` union, required - … - `tableSettings` TableSettings - … - TopKChart - `id` string, required - `sectionId` string, uuid - `type` 'TopK', required - `name` string - `query` union, required - … - StatisticChart - `id` string, required - `sectionId` string, uuid - `type` 'Statistic', required - `name` string - `query` union, required - … - `colorScheme` 'Blue' | 'Orange' | 'Red' | 'Purple' | 'Teal' | 'Yellow' | 'Green' | 'Pink' | 'Grey' | 'Brown' - `customUnits` string - `showChart` union - … - `hideValue` boolean - `chartHeight` union - … - `errorThreshold` 'Above' | 'AboveOrEqual' | 'Below' | 'BelowOrEqual' | 'AboveOrBelow' - `errorThresholdValue` string - `warningThreshold` 'Above' | 'AboveOrEqual' | 'Below' | 'BelowOrEqual' | 'AboveOrBelow' - `warningThresholdValue` string - `roundTo` integer - `invertTheme` boolean - `background` string - `textColor` string - `labelColor` string - `chartFillColor` string - `okColorProps` StatisticChartColorProps - … - `warningColorProps` StatisticChartColorProps - … - `errorColorProps` StatisticChartColorProps - … - GaugeChart - `id` string, required - `sectionId` string, uuid - `type` 'Gauge', required - `name` string - `query` union, required - … - `segments` GaugeChartSegment[], required - … - `colorScale` 'green-to-red' | 'red-to-green' - `showRing` boolean - `labelMode` 'none' | 'boundaries' | 'intervals' - `showSparkline` boolean - `scaleToTimeRange` boolean - `scaleBaseDurationMs` number - `customUnits` string - NoteChart - `id` string, required - `sectionId` string, uuid - `type` 'Note', required - `text` string, required - `variant` '' | 'default' | 'plain', nullable - MonitorListChart - `id` string, required - `sectionId` string, uuid - `type` 'MonitorList', required - `name` string - `selectedMonitors` string[], required - `columns` MonitorListColumns, required - … - SmartFilterChart - `id` string, required - `sectionId` string, uuid - `type` 'SmartFilter', required - `name` string - `filters` SmartFilterConfig[], required - … - `logo` string - `logoDark` string - SpacerChart - `id` string, required - `sectionId` string, uuid - `type` 'Spacer', required - `name` string - `variant` 'transparent' | 'dashed' | 'solid' - VisualizeChart - `id` string, required - `sectionId` string, uuid - `type` 'Visualize', required - `name` string - `query` union, required - … - `visualization` union, required - … - `layout` LayoutItem[], required - `i` string, required - `x` integer, required - `y` number, nullable, required - `w` integer, required - `h` number, required - `minW` integer - `minH` number - `maxW` integer - `maxH` integer - `static` boolean - `sections` Section[] - `id` string, uuid, required - `title` string, required - `defaultCollapsed` boolean - `refreshTime` 0 | 15 | 60 | 300, required - `schemaVersion` 2, required - `against` '-1h' | '-3h' | '-6h' | '-12h' | '-1d' | '-3d' | '-7d' | '-1w' | '-2w' | '-3w' | '-30d' | '-60d' | '-90d': Relative time comparison offset. Compares the current time window against a previous period offset by this duration. Mutually exclusive with `againstTimestamp` — setting one clears the other. Use an empty string or omit to disable comparison. - `againstTimestamp` string: A datetime value. Accepts ISO 8601 (e.g. `2024-01-02T00:00:00.000Z`), relative time using `now-{duration}` where duration is a number followed by `s` (seconds), `m` (minutes), `h` (hours), `d` (days), or `w` (weeks) (e.g. `now-1h`, `now-7d`), a Unix epoch millisecond timestamp as a string (e.g. `1704067200000`), or an empty string to clear the value. - `timeWindowStart` string, required: Start of the dashboard time range. Use `qr-now-{duration}` for a quick range relative to now, where duration is a number followed by `s` (seconds), `m` (minutes), `h` (hours), `d` (days), or `w` (weeks). Examples: `qr-now-5m`, `qr-now-1h`, `qr-now-7d`. Alternatively, use a Unix epoch millisecond timestamp as a string (e.g. `1704067200000`). - `timeWindowEnd` string, required: End of the dashboard time range. Use `qr-now` for a rolling window that tracks the current time (pair with a `qr-now-{duration}` start), or a Unix epoch millisecond timestamp as a string (e.g. `1704153600000`). - `uid` string: Optional dashboard UID. Must contain only letters, numbers, underscores, or hyphens, with length 1-128 when provided. - `id` string, required - `labelIds` LabelID[], required - `labelNames` string[]: Names of assigned labels, including with exclude=labels; [] when unassigned. - `labels` Label[] - `color` LabelColor, required - `name` 'red' | 'coral' | 'orange' | 'amber' | 'yellow' | 'lime' | 'green' | 'teal' | 'blue' | 'iris' | 'purple' | 'pink', required - `type` 'palette', required - `description` string, nullable - `id` string, required - `name` string, required - `type` 'managed' | 'integration', required: Managed dashboards are saved documents; integration dashboards are read-only and generated for matching datasets. - `uid` string, required: Managed dashboard UID, or stable integration dashboard ID for read requests. - `updatedAt` string, date-time, nullable: Last save time, present only for managed dashboards. - `updatedBy` string, nullable: Last editor, present only for managed dashboards. - `updatedByAgent` boolean: true when the last save came from the MCP server - `version` integer, nullable: Save version, present only for managed dashboards. - `overwritten` boolean - `status` 'created' | 'updated', required ## Other responses - `201`: Created dashboard - `400`: Invalid dashboard payload - `409`: Dashboard already exists - `412`: Version conflict ## Changes - **2026-11-02** (v2) `e3baf3b85e8d`: 20 breaking, 7 info - the response property `dashboard/createdAt` became nullable for the status `200` - the response property `dashboard/createdAt` became nullable for the status `201` - the response property `dashboard/createdBy` became nullable for the status `200` - the response property `dashboard/createdBy` became nullable for the status `201` - …23 more - **2026-10-14** (v2) `8920e1697284`: 4 info - added the optional property `dashboard/labels` to the response with the `200` status - added the optional property `dashboard/labels` to the response with the `201` status - added the required property `dashboard/labelIds` to the response with the `200` status - added the required property `dashboard/labelIds` to the response with the `201` status [Operation history](https://skmtc.dev/axiom/apis/axiom-public-api/changes/dashboards/post.md) --- [API](https://skmtc.dev/axiom/apis/axiom-public-api.md) - [All operations](https://skmtc.dev/axiom/apis/axiom-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/axiom/apis/axiom-public-api/revisions/7e39a295e3ba?raw)