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 Sections, each containing Rows of Widgets, parameterized by Variables and annotated with Annotations. 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.

Authentication and permissions

To use the Dashboard service API you need to create a personal or team API key. 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 tutorial on the user-guide side. For folder operations (list, get, create, replace, delete), see the Dashboard folders service.

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.
`variables_v2`	`[VariableV2]`	Dashboard parameterization — see Variables (V2). The legacy `variables` field is deprecated.
`variables`	`[Variable]`	Deprecated. Use `variables_v2`. See Variables (V1, deprecated).
`filters`	`[Filter]`	Dashboard-wide filters — see Filters.
`annotations`	`[Annotation]`	Dashboard-wide event annotations — see Annotations.
`actions`	`[DashboardAction]`	Public actions available within the dashboard — see 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.
`auto_refresh`	`oneof`	One of: `off`, `one_minute`, `two_minutes`, `five_minutes`, `fifteen_minutes`. See the Auto-refresh tutorial on the user-guide side.

For broader product context, see Manage dashboard settings.

Layout

A Layout is an ordered list of Sections. Each Section contains an ordered list of Rows, and each Row contains an ordered list of Widgets. The hierarchy is fixed at three levels: Layout → Section → Row → Widget. For the user-facing concept and UI walkthrough, see the 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).

For user-facing widget creation walkthroughs, see Add monitoring data to widgets and the getting-started guide. 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. 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. 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)). For user-facing variable concepts and UI walkthroughs, see 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). 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

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.

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. 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.

AnnotationColor (enum) — color the annotation renders with.
AnnotationOrientation (enum) — vertical / horizontal placement for metrics-sourced annotations.

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 Timestamps. 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.

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/<EnumName> 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.

Replace a dashboard folder Add dashboard to favorites

⌘I

​Dashboard service overview

​Authentication and permissions

​Common error response codes

​Endpoints

​Dashboards (CRUD, pinning, slug, folder assignment)

​Dashboard catalog

​Dashboard payload

​Layout

​Section

​Row

​Widgets

​Cross-dashboard widget reuse

​Widget catalog

​Variables (V1, deprecated)

​Variables (V2)

​Source (VariableSourceV2)

​Value (VariableValueV2)

​Filters

​Annotations

​Source (Annotation.Source)

​Scope — Annotation.WidgetScope (v5 only)

​Events (AnnotationEvent)

​Related types

​Widget-side: filtering an annotation’s series

​Time frame

​Actions

​Constants