> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coralogix.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
# Dashboard service overview
The Dashboard service API manages Coralogix dashboards: it lets you create, retrieve, update, delete, and organize dashboards, pin them to favorites, and look up a catalog of every dashboard the caller can see. A *dashboard* is a JSON payload describing a `Layout` of `Section`s, each containing `Row`s of `Widget`s, parameterized by `Variable`s and annotated with `Annotation`s. The same payload is consumed by Create and Replace operations and returned by Get.
This overview describes:
* The 10 endpoints exposed by the Dashboards service (CRUD + pinning + slug lookup + folder assignment + catalog).
* The structure of the dashboard payload (`Dashboard` message and its components).
* The widget, variable, filter, annotation, and action types that compose a dashboard.
For user-facing concept introductions and step-by-step tutorials, see the [Custom Dashboards user guide](https://coralogix.com/docs/user-guides/custom-dashboards/getting-started/).
## Authentication and permissions
To use the Dashboard service API you need to [create a personal or team API key](https://coralogix.com/docs/user-guides/account-management/api-keys/api-keys/). It's recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add the following individual permissions.
| Presets | Permission | Description |
| ---------- | ------------------------ | ----------------------------------------------------- |
| Dashboards | `team-dashboards:Read` | Grants access to read team-dashboards |
| | `team-dashboards:Update` | Required to create, update, or delete team-dashboards |
## Common error response codes
| Status Code | Description |
| --------------------------- | ----------------- |
| `400 Bad Request` | Response code 400 |
| `401 Unauthorized` | Response code 401 |
| `500 Internal Server Error` | Response code 500 |
## Endpoints
### Dashboards (CRUD, pinning, slug, folder assignment)
| Method | Path | Summary |
| -------- | -------------------------------------------------- | ------------------------------- |
| `POST` | `/dashboards/dashboards/v1` | Create a new dashboard |
| `PUT` | `/dashboards/dashboards/v1` | Replace a dashboard |
| `GET` | `/dashboards/dashboards/v1/{dashboard_id}` | Get a dashboard |
| `DELETE` | `/dashboards/dashboards/v1/{dashboard_id}` | Delete a dashboard |
| `GET` | `/dashboards/dashboards/v1/slugs/{slug}` | Get a dashboard by URL slug |
| `PUT` | `/dashboards/dashboards/v1/{dashboard_id}/default` | Replace the default dashboard |
| `POST` | `/dashboards/dashboards/v1/{dashboard_id}/folder` | Assign a dashboard to a folder |
| `PUT` | `/dashboards/pinned/v1/{dashboard_id}` | Add dashboard to favorites |
| `DELETE` | `/dashboards/pinned/v1/{dashboard_id}` | Remove dashboard from favorites |
### Dashboard catalog
| Method | Path | Summary |
| ------ | ----------------------------------- | --------------------- |
| `GET` | `/dashboards/dashboards/v1/catalog` | Get dashboard catalog |
The catalog endpoint mirrors the [Manage dashboard catalog](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/manage-dashboard-catalog/) tutorial on the user-guide side.
For folder operations (list, get, create, replace, delete), see the [Dashboard folders service](../dashboard-folders-service/overview).
## Dashboard payload
The `Dashboard` message is the unit accepted by Create / Replace and returned by Get. Required fields: `name` and `layout`. All other fields are optional.
| Field | Type | Notes |
| ---------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | A unique identifier of the dashboard. |
| `name` | `string` | **Required.** Display name. |
| `description` | `string` | Optional summary of the dashboard's purpose. |
| `slug_name` | `string` | Optional alias used by `GET /slugs/{slug}`. |
| `layout` | `Layout` | **Required.** Sections, rows, and widgets — see [Layout](#layout). |
| `variables_v2` | `[VariableV2]` | Dashboard parameterization — see [Variables (V2)](#variables-v2). The legacy `variables` field is deprecated. |
| `variables` | `[Variable]` | *Deprecated.* Use `variables_v2`. See [Variables (V1, deprecated)](#variables-v1-deprecated). |
| `filters` | `[Filter]` | Dashboard-wide filters — see [Filters](#filters). |
| `annotations` | `[Annotation]` | Dashboard-wide event annotations — see [Annotations](#annotations). |
| `actions` | `[DashboardAction]` | Public actions available within the dashboard — see [Actions](#actions). |
| `folder_id` or `folder_path` | `string` / `FolderPath` | Mutually exclusive. Either reference an existing folder by id, or supply a `FolderPath` (list of segments) to place the dashboard. |
| `time_frame` | `oneof` | `absolute_time_frame` (`{from, to}` timestamps) or `relative_time_frame` (a duration relative to "now"). See [Time frame](#time-frame). |
| `auto_refresh` | `oneof` | One of: `off`, `one_minute`, `two_minutes`, `five_minutes`, `fifteen_minutes`. See the [Auto-refresh](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/auto-refresh/) tutorial on the user-guide side. |
For broader product context, see [Manage dashboard settings](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/manage-dashboard-settings/).
## Layout
A `Layout` is an ordered list of `Section`s. Each `Section` contains an ordered list of `Row`s, and each `Row` contains an ordered list of `Widget`s. The hierarchy is fixed at three levels: `Layout → Section → Row → Widget`.
For the user-facing concept and UI walkthrough, see the [Sections](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/sections/) tutorial.
### Section
| Field | Type | Notes |
| --------- | ---------------- | ------------------------------------------------------- |
| `id` | `UUID` | Section's unique identifier. |
| `rows` | `[Row]` | Rows in the section. |
| `options` | `SectionOptions` | A `oneof` over `internal` (system-managed) or `custom`. |
`CustomSectionOptions` carries: `name`, `description`, `collapsed` (boolean), `color` (a `SectionPredefinedColor` enum: cyan / green / blue / purple / magenta / pink / orange), and optionally a `repetitive_var` (a variable name that turns the section into a repeating block — one rendered copy per selected value of that variable).
### Row
| Field | Type | Notes |
| ------------------- | ---------- | ------------------------------------------------------------------------------ |
| `id` | `UUID` | Row's unique identifier. |
| `appearance.height` | `int32` | Height multiplier — `1` = one unit of base height, `2` = two units, and so on. |
| `widgets` | `[Widget]` | Widgets to render side-by-side in this row. |
## Widgets
A `Widget` carries either a `definition` (an inline widget configuration) **or** a `reference` (a `WidgetReference` pointing at a widget defined on another dashboard). The two are mutually exclusive — the backend rejects payloads that set both or neither.
| Field | Type | Notes |
| ------------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `id` | `UUID` | Widget's unique identifier. |
| `title` | `string` | Display name. |
| `description` | `string` | Optional caption. |
| `definition` | `Widget.Definition` | A `oneof` over the 9 widget types listed below. |
| `reference` | `WidgetReference` | Alternative to `definition` (see [Cross-dashboard widget reuse](#cross-dashboard-widget-reuse)). |
For user-facing widget creation walkthroughs, see [Add monitoring data to widgets](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/add-monitoring-data-to-custom-dashboard-widgets/) and the [getting-started guide](https://coralogix.com/docs/user-guides/custom-dashboards/getting-started/#add-new-widgets).
### Cross-dashboard widget reuse
A `WidgetReference` re-renders a widget defined on a different dashboard:
| Field | Type | Notes |
| -------------- | -------- | ------------------------------------------------ |
| `dashboard_id` | `string` | ID of the dashboard that owns the source widget. |
| `widget_id` | `UUID` | ID of the widget within that dashboard. |
Use a reference when you want a widget to appear on multiple dashboards without copying its definition; updates to the source widget propagate to every dashboard that references it.
## Widget catalog
Each widget's `definition` is a `oneof` over the variants below. Every chart accepts a query over one of four data sources — Logs (Lucene), Spans (Lucene), Metrics (PromQL), or DataPrime — except `Markdown`, which carries no query. For the full field set per widget (color schemes, legend, axis bounds, units, etc.), see the corresponding schema in `openapi_v5.yaml`.
| Widget | Purpose |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LineChart` | Time-series lines; supports multi-query overlays via `query_definitions`. |
| `BarChart` | Vertical bars; single-query. |
| `HorizontalBarChart` | Horizontal-orientation bars; mirrors `BarChart` with axis-handling differences. |
| `PieChart` | Pie or donut chart; single-query. |
| `Gauge` | Single-value gauge with min/max range and threshold bands. |
| `Hexagon` | Single-value hex cell, typically used in a hex grid. |
| `DataTable` | Tabular renderer with developer-defined columns; for the dynamic-table variant use `Dynamic widget`. |
| `Markdown` | Static prose panel; no query. |
| `Dynamic widget` | Query-driven widget that picks its renderer at runtime via `interpretation` + `visualization` — see [Build a dynamic table widget](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/build-a-dynamic-table-widget/). The legacy `query` field is deprecated; populate `query_definitions` only. |
## Variables (V1, deprecated)
The `Dashboard.variables` field uses the **V1** variable model (proto package `variables`). It is deprecated; new dashboards should populate `variables_v2` instead (see [Variables (V2)](#variables-v2)).
For user-facing variable concepts and UI walkthroughs, see [Create and manage variables](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-and-manage-variables/).
A V1 `Variable` has `name`, optional `display_name` / `description`, a `display_type` (`VariableDisplayType` enum), and a `Definition`. The `Definition.value` is a `oneof` over:
* **`Constant`** — *(deprecated within V1)* a single fixed value.
* **`MultiSelect`** — a value selected from a list, sourced from one of: a logs path (`LogsPathSource`), a metric label (`MetricLabelSource`), a constant list (`ConstantListSource`), a span field (`SpanFieldSource`), or an arbitrary query (`QuerySource`). Supports `selection` (single or multi-value), an `OrderDirection`, and `VariableSelectionOptions`.
V1 schemas remain in the spec for backward compatibility with existing dashboards. The `MultiSelect.selected` field within V1 is also marked deprecated — current dashboards encode the user's selection through `VariableSelectionOptions` and the consuming UI.
## Variables (V2)
Variables let a dashboard accept user-supplied or query-derived values that are substituted into widget queries at view time. The dashboard payload carries the **V2** variable model (proto package `com.coralogixapis.dashboards.v1.ast.variables_v2`); the older V1 model (`Variable` / `Variable.Definition` / `VariableDefinitionConstant` / `VariableDefinitionMultiSelect`) is still present in the spec for backward compatibility — see [Variables (V1, deprecated)](#variables-v1-deprecated).
A `VariableV2` carries: a unique `id` (UUID), `name`, optional `display_name` and `description`, a `display_type` (`VariableDisplayTypeV2` enum — values in the collapsible below), a `source` that produces candidate values, a `value` selection, and a `display_full_row` toggle.
### Source (`VariableSourceV2`)
A `oneof` over three variants:
* **`QuerySource`** — values come from a Coralogix query against logs, spans, metrics, or DataPrime. Carries a `refresh_strategy`, `value_display_options` (label/value regex), and an `all_option`.
* **`StaticSource`** — values are an inline list (with an `all_option`).
* **`TextboxSource`** — value is free-form text entered in the dashboard UI.
`QuerySource` has four sub-variants matching its data source: `LogsQuery`, `SpansQuery`, `MetricsQuery`, `DataprimeQuery` (openapi schema names: `VariableSourceV2QuerySourceLogsQuery`, `…SpansQuery`, `…MetricsQuery`, `…DataprimeQuery`).
### Value (`VariableValueV2`)
A `oneof` over six variants (proto names):
* `SingleStringValue`
* `SingleNumericValue`
* `MultiStringValue` — wraps either an `AllValue`, a `ListValue`, or a `SelectedAllValue`
* `LuceneQueryValue`
* `RegexValue`
* `IntervalValue`
VariableDisplayTypeV2
| Value |
| -------------------------------------- |
| `VARIABLE_DISPLAY_TYPE_V2_UNSPECIFIED` |
| `VARIABLE_DISPLAY_TYPE_V2_LABEL_VALUE` |
| `VARIABLE_DISPLAY_TYPE_V2_VALUE` |
| `VARIABLE_DISPLAY_TYPE_V2_NOTHING` |
For the full message structure, see the `VariableV2`, `VariableSourceV2.*`, `VariableValueV2.*`, and `VariableDisplayTypeV2` schemas in `openapi_v5.yaml`. For user-facing variable usage, see [Create and manage variables](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-and-manage-variables/).
## Filters
A `Filter` constrains the data that widgets render. Each filter has:
| Field | Type | Notes |
| -------------- | -------------------- | ---------------------------------------------------------------- |
| `id` | `UUID` | Filter's unique identifier. |
| `display_name` | `string` | Optional UI label. |
| `enabled` | `boolean` | Whether the filter currently applies. |
| `collapsed` | `boolean` | UI hint — whether the filter chip renders collapsed or expanded. |
| `source` | `Filter.Source` | A `oneof` over `LogsFilter`, `SpansFilter`, or `MetricsFilter`. |
| `scope` | `Filter.WidgetScope` | Which widgets the filter targets. |
`Filter.WidgetScope` is a `oneof` over:
* **`AllWidgets`** — the filter applies to every widget on the dashboard.
* **`SpecificWidgets`** — the filter applies only to the listed `widget_ids`.
Each `Source` variant carries source-appropriate fields (e.g., `LogsFilter` carries `field`, `operator`, and `observation_field`). For the full per-source field list, see the `Filter.LogsFilter`, `Filter.SpansFilter`, and `Filter.MetricsFilter` schemas in `openapi_v5.yaml`.
## Annotations
Annotations mark significant events on dashboard widgets — for example, deploys, incidents, or business milestones — so they appear as overlays on charts that match their scope. An annotation is sourced from a Coralogix query, manual input, or a recurring event, and can be scoped to all widgets on the dashboard or a specific set.
For user-facing concept and creation walkthrough, see [Create annotations](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/create-annotations/).
An `Annotation` message has:
* `id` — unique identifier
* `name` — display name
* `description` — optional description
* `enabled` — boolean toggle
* `source` — where the events come from (see below)
* `scope` — which widgets the annotation overlays
* `color` — an `AnnotationColor` enum value
### Source (`Annotation.Source`)
A `oneof` over six source types:
* **`MetricsSource`** — events from a PromQL query (`promql_query`). Carries a `Strategy` (currently `StartTimeMetric` — uses the first data point's value as the annotation timestamp), a `message_template`, label list, `AnnotationOrientation`, and an `IntervalResolution`.
* **`LogsSource`** — events from a Lucene logs query (`lucene_query`). The strategy is a `oneof` over `Instant` (single timestamp field), `Range` (start + end timestamp fields), and `Duration` (start timestamp + duration field). Supports `label_fields` and `DataModeType`.
* **`SpansSource`** — same shape as `LogsSource` but over spans.
* **`DataprimeSource`** — events from a DataPrime query (`query`) with the same Instant/Range/Duration strategy variants.
* **`ManualSource`** — manually configured events with an `Instant` (single `value` + `Unit`) or `Range` (`start_value` / `end_value` + `Unit`) strategy. Optional `custom_unit`, `message_template`, and `AnnotationOrientation`.
* **`EventRecurrenceSource`** — events from a recurring schedule. Currently only `WeeklyRecurrence` (with selectable `days_of_week` from a `Weekday` enum) is supported, paired with an `Instant` (start hour) or `Duration` (start hour + length) strategy.
### Scope — `Annotation.WidgetScope` (v5 only)
`Annotation.WidgetScope` is a `oneof` over:
* **`AllWidgets`** — annotation overlays every widget on the dashboard.
* **`SpecificWidgets`** — annotation overlays only the listed `widget_ids`.
Earlier spec versions (`v3`, `v4`) do not scope annotations to specific widgets — that surface is v5-only. (A separate top-level `WidgetScope` family exists in `v3` and `v4` for `Filter` scoping; it's unrelated to annotations.)
### Events (`AnnotationEvent`)
When the dashboard renders an annotation, each emitted event is either:
* **`Instant`** — a point in time with `timestamp`, `labels`, and `payload`.
* **`Range`** — a span with `start`, `end`, `labels`, and `payload`.
### Related types
* `AnnotationColor` *(enum)* — color the annotation renders with.
* `AnnotationOrientation` *(enum)* — vertical / horizontal placement for metrics-sourced annotations.
### Widget-side: filtering an annotation's series
`AnnotationSeriesVisibility` is **not** part of the `Annotation` message — it's defined alongside the widget-level `SeriesVisibility` schema. It's an entry inside a widget's `SeriesVisibility.annotation_series` list, with `annotation_id`, a `SeriesVisibilityMode` (`HIDE_ALL` / `SHOW_ONLY`), and a `series_names` list. Use it on the widget side to control which series of an already-defined annotation render on that widget.
For the full message structure, see the `Annotation` and `Annotation.Source.*` schema families in `openapi_v5.yaml`.
## Time frame
The dashboard's time frame is a `oneof`:
* **`absolute_time_frame`** — a `TimeFrame` with `from` and `to` protobuf `Timestamp`s. Fixed start and end times.
* **`relative_time_frame`** — a `google.protobuf.Duration` interpreted as an offset from "now."
A dashboard-level time frame applies to every widget by default. Individual widgets (for example, the Dynamic widget) can override the dashboard time frame on a per-widget basis.
For the user-facing time-interval picker UI, see [Configure time interval](https://coralogix.com/docs/user-guides/custom-dashboards/tutorials/configure-time-interval/).
## Actions
The dashboard payload carries `actions` as a list of `DashboardAction` — publicly available actions a viewer can trigger from a dashboard or one of its widgets.
| Field | Type | Notes |
| --------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | `string` | A unique identifier of the action. |
| `name` | `string` | Display name. |
| `should_open_in_new_window` | `boolean` | Whether the action opens in a new tab/window. |
| `widget_id` | `string` *(optional)* | Scopes the action to a specific widget. Null = dashboard-wide. |
| `query_id` | `string` *(optional)* | Scopes the action to a specific query within a widget. Null = widget-wide or dashboard-wide. |
| `definition` | `ActionDefinition` | A `oneof` over `CustomAction` (a URL template with `{{variable_name}}` placeholders) or `GoToDashboardTemplateAction` (`dashboard_id` of the target dashboard). |
| `data_source` | `ActionDataSourceType` *(optional)* | One of `LOGS`, `SPANS`, `METRICS`, `DATAPRIME`. |
The `Custom URL` template supports variable substitution: any `{{variable_name}}` in the URL is replaced with the matching variable's resolved value when the user clicks the action.
> **Note:** A separate, older `Action` message exists in the spec but is marked deprecated. The proto file describes it as "Unused dormant model that was part of plans of the product team, however it is now on hold. Recommended to not use this model or rely on it in any way." Always use `DashboardAction` for the `Dashboard.actions` field.
## Constants
This service references a number of enum types across query, display, variable, and identity schemas. For the full value list of each enum, see `#/components/schemas/` in `openapi_v5.yaml`. Notable enums:
* **Query and data source:** `ActionDataSourceType`, `DataModeType`, `LogSeverityLevel`, `PromQLQueryType`, `SpanRelationType`, `MetricField`, `MetricAggregationType`, `DimensionField`, `DimensionAggregationType`, `MetadataField`, `DatasetScope`, `MetricsQueryEditorMode`, `Aggregation`, `AggregationType`, `SortByType`, `OrderDirection`.
* **Display and layout:** `VariableDisplayType`, `RefreshStrategy`, `SelectionType`, `TooltipType`, `StackedLine`, `RowStyle`, `BarValueDisplay`, `LabelSource`, `ScaleType`, `LegendColumn`, `LegendPlacement`, `LegendBy`, `Unit`, `ThresholdBy`, `ThresholdType`, `SectionPredefinedColor`.
* **Identity:** `TokenOriginType`.