Technical Reference

DTO Reference

Complete JSON specification for all KnowMine graph widget API responses. All graph widgets share the same response envelope; the payload field contains chart-specific data.

This reference describes what your API must return. If you prefer a ready-made implementation, check out the knowmine-graphs open source library.

Response Envelope

Every API endpoint must return a JSON object with the following top-level structure.

{ "name": "Widget Title", "type": "WidgetTypeName", "version": "1.0", "payload": { "..." }, "refreshInterval": 30, "backgroundColor": { "type": "Fill | Gradient", "primaryColor": "#RRGGBB", "secondaryColor": "#RRGGBB" }, "backgroundType": "NONE | RECT | ROUND_RECT | ...", "borderColor": "#RRGGBB | primary_color | ...", "shadowColor": "#RRGGBB | primary_color | ..." }

Field	Type	Req	Default	Notes
`name`	`string`	❌	null	Widget display name. User can override in-app.
`type`	`string`	✅	—	Widget type identifier. Case-sensitive. See chart types below.
`version`	`string`	❌	null	Datasource format version (e.g. `"1.0"`). Reserved for future use.
`payload`	`object`	✅	—	Chart-specific data. See each chart type.
`refreshInterval`	`number`	❌	`30`	Auto-refresh in seconds. Min: 5, Max: 60.
`backgroundColor`	`ColorSpec`	❌	null	Widget container background.
`backgroundType`	`string`	❌	`"NONE"`	Background shape. See Background Types.
`borderColor`	`string`	❌	null	Border color. Hex or palette key.
`shadowColor`	`string`	❌	null	Shadow color. Hex or palette key.

Shared Types

Color Strings

Any field accepting a color string supports two formats:

Hex: "#RRGGBB" (6 digits) or "#RRGGBBAA" (8 digits with alpha)
Palette keys that resolve to the user's active page theme:

Key	Resolved color
`"primary_color"`	Page primary color
`"secondary_color"`	Page secondary color
`"background_color"`	Page background color
`"text_color"`	Page text color
`"accent_color"`	Page accent color
`"custom_color"`	Page custom color

ColorSpec

{ "type": "Fill", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }

Field	Type	Req	Notes
`type`	`"Fill" \| "Gradient"`	✅	`Fill` = solid, `Gradient` = two-color gradient
`primaryColor`	`string`	✅	Hex or palette key. For gradients: start/center color.
`secondaryColor`	`string`	❌	Required when `type` is `"Gradient"`. End/outer color.

FontModel

{ "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF", "secondaryColor": "#000000" } }

Field	Type	Req	Notes
`font`	`string`	✅	Font raw value (e.g. `"Lato-Regular"`, `"Orbitron-Bold"`).
`color.type`	`"FILL" \| "GRADIENT" \| "NONE"`	✅	Color type (uppercase).
`color.color`	`string`	✅	Primary hex color.
`color.secondaryColor`	`string`	❌	Required when `color.type` is `"GRADIENT"`.

namePosition

Controls the position of the widget title relative to the chart.

Value	Description
`"TOP_LEFT"`	Top, left-aligned (default)
`"TOP"`	Top, centered
`"TOP_RIGHT"`	Top, right-aligned
`"BOTTOM_LEFT"`	Bottom, left-aligned
`"BOTTOM"`	Bottom, centered
`"BOTTOM_RIGHT"`	Bottom, right-aligned

"LEFT", "CENTER", "RIGHT" are not supported.

YAxisPosition

Controls the Y-axis display mode. Applies to BarChart, AreaChart, TimeSeriesLineChart, and StackedBarChart.

Value	Scale	Labels	Side
absent / `"NONE"`	Auto	None	—
`"AUTO"`	Auto	Auto-generated (min, mid, max)	Left
`"LEFT"`	Fixed if yMin/yMax present	From `yAxisLabels`	Left only
`"RIGHT"`	Fixed if yMin/yMax present	From `yAxisLabels`	Right only
`"BOTH"`	Fixed if yMin/yMax present	From `yAxisLabels`	Both sides

Each side reserves 28pt (no unit) or 44pt (with yAxisUnit) inside horizontal padding.

Background Types

Valid values for backgroundType:

NONE RECT ROUND_RECT ROUND_RECT_TL ROUND_RECT_TR ROUND_RECT_BL ROUND_RECT_BR ROUND_RECT_TL_NEG ROUND_RECT_TR_NEG ROUND_RECT_BL_NEG ROUND_RECT_BR_NEG ROUND_RECT_OPP_1 ROUND_RECT_OPP_2 ROUND_RECT_TOP ROUND_RECT_LEFT ROUND_RECT_BOTTOM ROUND_RECT_RIGHT SMALL_ROUND_RECT

Chart Types

1. BarChart

type: "BarChart" 2×1

Vertical bar chart with gradient support, optional single-bar highlight, and configurable corner radius.

Example Response

{ "name": "Monthly Sales", "type": "BarChart", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "values": [8.0, 14.0, 10.0, 18.0, 12.0, 22.0], "highlightIndex": 5, "barColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "highlightColor": { "type": "Fill", "primaryColor": "#FF8C00" }, "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], "labelColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "yAxisLabels": ["0", "11", "22"], "yAxisUnit": null, "yAxisPosition": "LEFT", "yAxisLabelColor": { "type": "Fill", "primaryColor": "#FFFFFF99" }, "yMin": 0, "yMax": 22, "barSpacing": 4, "cornerRadius": 6, "showGlow": false, "horizontalPadding": 12, "verticalPadding": 10, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`values`	`number[]`	✅	—	Bar values. At least one required.
`barColor`	`ColorSpec`	✅	—	Color applied to all standard bars.
`highlightIndex`	`number`	❌	null	0-based index of the highlighted bar.
`highlightColor`	`ColorSpec`	❌	—	Required if `highlightIndex` is present.
`labels`	`string[]`	❌	null	Text labels below each bar.
`labelColor`	`ColorSpec`	❌	Fill #FFFFFF	Label text color.
`yAxisLabels`	`string[]`	❌	null	Y-axis labels. Used with LEFT/RIGHT/BOTH.
`yAxisUnit`	`string`	❌	null	Unit suffix on Y-axis labels (e.g. `"KB/s"`).
`yAxisPosition`	`string`	❌	null	See YAxisPosition.
`yAxisLabelColor`	`ColorSpec`	❌	Fill #FFFFFF	Y-axis label color.
`yMin`	`number`	❌	null	Scale minimum. Required for fixed scale mode.
`yMax`	`number`	❌	null	Scale maximum. Required for fixed scale mode.
`barSpacing`	`number`	❌	`4`	Gap between bars in points.
`cornerRadius`	`number`	❌	`6`	Bar corner radius in points.
`showGlow`	`boolean`	❌	`false`	Glow on the highlighted bar.
`horizontalPadding`	`number`	❌	`12`	Horizontal canvas padding.
`verticalPadding`	`number`	❌	`10`	Vertical canvas padding.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title font and color.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position. See namePosition.

2. PieChart

type: "PieChart" 1×1 · 2×1

Full pie or donut chart. Each slice has its own color. In 2×1, a legend is shown on the right (up to 5 entries; >5 slices aggregate as "Others").

Example Response

{ "name": "Expense Breakdown", "type": "PieChart", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "slices": [ { "value": 40.0, "color": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "label": "Alpha", "labelColor": { "type": "Fill", "primaryColor": "#00FFFF" } }, { "value": 35.0, "color": { "type": "Gradient", "primaryColor": "#FF8C00", "secondaryColor": "#FF0000" }, "label": "Beta", "labelColor": { "type": "Fill", "primaryColor": "#FF8C00" } }, { "value": 25.0, "color": { "type": "Gradient", "primaryColor": "#800080", "secondaryColor": "#4B0082" }, "label": "Gamma", "labelColor": { "type": "Fill", "primaryColor": "#CC66FF" } } ], "innerRadiusRatio": 0.5, "sliceSpacing": 3, "outerPadding": 10, "showGlow": false, "showPercentage": false, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`slices`	`SliceSpec[]`	✅	—	Array of slices drawn clockwise from -90°.
`slices[].value`	`number`	✅	—	Slice value (auto-normalized to total).
`slices[].color`	`ColorSpec`	✅	—	Slice color. For gradients: center→outer edge.
`slices[].label`	`string`	❌	null	Legend label (2×1 only).
`slices[].labelColor`	`ColorSpec`	❌	Semi-white	Legend label color.
`innerRadiusRatio`	`number`	❌	`0.0`	`0` = full pie, `0.5` = donut. Range 0–0.9.
`sliceSpacing`	`number`	❌	`3`	Gap between slices in points.
`outerPadding`	`number`	❌	`10`	Padding between pie edge and canvas.
`showGlow`	`boolean`	❌	`false`	Glow effect on each slice.
`glowColor`	`ColorSpec`	❌	Fill #FFF	Glow color (if `showGlow` is true).
`showPercentage`	`boolean`	❌	`false`	Show percentage next to each legend entry.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title font and color.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position. See namePosition.

3. AreaChart

type: "AreaChart" 2×1

Area chart with a top line and vertically-gradient fill. Supports a configurable baseline and optional X-axis labels. Ideal for trends over time.

Example Response

{ "name": "Weekly Temperature", "type": "AreaChart", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "values": [12.0, 15.0, 13.0, 18.0, 16.0, 22.0, 20.0], "baselineValue": 10.0, "lineColor": { "type": "Fill", "primaryColor": "#00FFFF" }, "areaColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#00000000" }, "lineWidth": 2.5, "smoothingEnabled": true, "showGlow": false, "horizontalPadding": 12, "verticalPadding": 10, "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"], "labelColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "yAxisLabels": ["10", "16", "22"], "yAxisPosition": "LEFT", "yAxisLabelColor": { "type": "Fill", "primaryColor": "#FFFFFF99" }, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`values`	`number[]`	✅	—	Chronological values. Minimum 2.
`lineColor`	`ColorSpec`	✅	—	Top line color.
`areaColor`	`ColorSpec`	✅	—	Area fill (opaque top → transparent bottom).
`baselineValue`	`number`	❌	null	Baseline for the area. Defaults to min value.
`glowColor`	`ColorSpec`	❌	—	Glow color. Required if `showGlow` is true.
`lineWidth`	`number`	❌	`2.5`	Line thickness in points.
`smoothingEnabled`	`boolean`	❌	`true`	Catmull-Rom smooth curve vs. straight polyline.
`showGlow`	`boolean`	❌	`false`	Glow effect on the line.
`horizontalPadding`	`number`	❌	`12`	Horizontal canvas padding.
`verticalPadding`	`number`	❌	`10`	Vertical canvas padding.
`labels`	`string[]`	❌	null	X-axis labels (1:1 per data point). Ignored if `xAxisLabels` present.
`labelColor`	`ColorSpec`	❌	Fill #FFF	Label color.
`showGrid`	`boolean`	❌	`false`	Background grid.
`gridRows`	`number`	❌	`4`	Horizontal grid rows.
`gridColumns`	`number`	❌	`6`	Vertical grid columns.
`gridColor`	`ColorSpec`	❌	Fill #FFFFFF26	Grid line color (if `showGrid` is true).
`xAxisLabels`	`string[]`	❌	null	N labels distributed geometrically. Priority over `labels`.
`xAxisLabelColor`	`ColorSpec`	❌	null	Color for `xAxisLabels`. Falls back to `labelColor`.
`yAxisLabels`	`string[]`	❌	null	Y-axis labels. Used with LEFT/RIGHT/BOTH.
`yAxisUnit`	`string`	❌	null	Unit suffix on Y-axis labels.
`yAxisPosition`	`string`	❌	null	See YAxisPosition.
`yAxisLabelColor`	`ColorSpec`	❌	Fill #FFF	Y-axis label color.
`yMin`	`number`	❌	null	Scale minimum. Required for fixed scale.
`yMax`	`number`	❌	null	Scale maximum. Required for fixed scale.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title font and color.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

4. TimeSeriesLineChart

type: "TimeSeriesLineChart" 2×1

Time series line with a horizontal gradient and vertical fill. Optional background grid. Suited for real-time or historical data with a technical dashboard look.

Example Response

{ "name": "Energy Consumption", "type": "TimeSeriesLineChart", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "values": [10.0, 13.0, 11.0, 17.0, 15.0, 20.0, 18.0, 24.0], "lineColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "areaColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#00000000" }, "gridColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "lineWidth": 2.5, "showGrid": true, "smoothingEnabled": true, "showGlow": false, "gridRows": 4, "gridColumns": 6, "horizontalPadding": 12, "verticalPadding": 10, "labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun", "Mon"], "labelColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "yAxisLabels": ["10", "17", "24"], "yAxisPosition": "LEFT", "yAxisLabelColor": { "type": "Fill", "primaryColor": "#FFFFFF99" }, "yMin": 10, "yMax": 24, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`values`	`number[]`	✅	—	Chronological values. Minimum 2.
`lineColor`	`ColorSpec`	✅	—	Line gradient (horizontal, left→right).
`areaColor`	`ColorSpec`	✅	—	Fill gradient (vertical, opaque→transparent).
`gridColor`	`ColorSpec`	❌	—	Grid color. Required if `showGrid` is true.
`glowColor`	`ColorSpec`	❌	—	Glow color. Required if `showGlow` is true.
`lineWidth`	`number`	❌	`2.5`	Line thickness.
`showGrid`	`boolean`	❌	`true`	Background grid.
`smoothingEnabled`	`boolean`	❌	`true`	Smooth curve.
`showGlow`	`boolean`	❌	`false`	Glow on the line.
`gridRows`	`number`	❌	`4`	Horizontal grid rows.
`gridColumns`	`number`	❌	`6`	Vertical grid columns.
`horizontalPadding`	`number`	❌	`12`	Horizontal canvas padding.
`verticalPadding`	`number`	❌	`10`	Vertical canvas padding.
`labels`	`string[]`	❌	null	X-axis labels (1:1). Ignored if `xAxisLabels` present.
`labelColor`	`ColorSpec`	❌	Fill #FFF	Label color.
`xAxisLabels`	`string[]`	❌	null	N labels distributed geometrically. Priority over `labels`.
`xAxisLabelColor`	`ColorSpec`	❌	null	Color for `xAxisLabels`.
`yAxisLabels`	`string[]`	❌	null	Y-axis labels. Used with LEFT/RIGHT/BOTH.
`yAxisUnit`	`string`	❌	null	Unit suffix on Y-axis labels.
`yAxisPosition`	`string`	❌	null	See YAxisPosition.
`yAxisLabelColor`	`ColorSpec`	❌	Fill #FFF	Y-axis label color.
`yMin`	`number`	❌	null	Scale minimum.
`yMax`	`number`	❌	null	Scale maximum.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

5. StackedBarChart

type: "StackedBarChart" 2×1

Multi-series stacked bars. Corner radius applied to top and bottom of the composed bar only. Good for part-to-whole relationships.

Example Response

{ "name": "Traffic by Category", "type": "StackedBarChart", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "series": [ { "values": [4.0, 6.0, 5.0, 8.0, 7.0, 9.0], "color": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#00CCCC" } }, { "values": [3.0, 4.0, 3.0, 5.0, 4.0, 6.0], "color": { "type": "Gradient", "primaryColor": "#0000FF", "secondaryColor": "#0000CC" } }, { "values": [2.0, 2.0, 3.0, 3.0, 2.0, 4.0], "color": { "type": "Gradient", "primaryColor": "#4B0082", "secondaryColor": "#36006E" } } ], "cornerRadius": 6, "barSpacing": 4, "showGlow": false, "horizontalPadding": 12, "verticalPadding": 10, "labels": ["Jan", "Feb", "Mar", "Apr", "May", "Jun"], "labelColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "yAxisLabels": ["0", "10", "19"], "yAxisPosition": "LEFT", "yAxisLabelColor": { "type": "Fill", "primaryColor": "#FFFFFF99" }, "yMin": 0, "yMax": 19, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`series`	`SeriesSpec[]`	✅	—	Array of series. First = bottom, last = top. Same count per series.
`series[].values`	`number[]`	✅	—	Values for each bar in this series.
`series[].color`	`ColorSpec`	✅	—	Color for this segment.
`cornerRadius`	`number`	❌	`6`	Applied to top and bottom of composed bar only.
`barSpacing`	`number`	❌	`4`	Gap between bars.
`showGlow`	`boolean`	❌	`false`	Glow on top segment.
`horizontalPadding`	`number`	❌	`12`	Horizontal canvas padding.
`verticalPadding`	`number`	❌	`10`	Vertical canvas padding.
`labels`	`string[]`	❌	null	Labels below each bar.
`labelColor`	`ColorSpec`	❌	Fill #FFF	Label color.
`yAxisLabels`	`string[]`	❌	null	Y-axis labels.
`yAxisUnit`	`string`	❌	null	Unit suffix on Y-axis labels.
`yAxisPosition`	`string`	❌	null	See YAxisPosition.
`yAxisLabelColor`	`ColorSpec`	❌	Fill #FFF	Y-axis label color.
`yMin`	`number`	❌	null	Scale minimum.
`yMax`	`number`	❌	null	Scale maximum.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

6. RadialGauge

type: "RadialGauge" 1×1

Arc gauge with configurable opening angle (nearly full circle to semicircle). Color thresholds override arc color based on value. Optional graduation ticks.

Example Response

{ "name": "CPU Usage", "type": "RadialGauge", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "value": 72.0, "minValue": 0.0, "maxValue": 100.0, "thresholds": [ { "value": 40.0, "color": { "type": "Fill", "primaryColor": "#00FF00" } }, { "value": 80.0, "color": { "type": "Fill", "primaryColor": "#FF8C00" } }, { "value": 100.0, "color": { "type": "Fill", "primaryColor": "#FF0000" } } ], "gaugeColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "gaugeBackgroundColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "valueTextColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "gapAngle": 120, "lineWidth": 14, "showTicks": false, "showGlow": false, "label": "CPU", "unit": "%", "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`value`	`number`	✅	—	Current value (clamped to min/max).
`minValue`	`number`	✅	—	Scale minimum.
`maxValue`	`number`	✅	—	Scale maximum.
`gaugeColor`	`ColorSpec`	✅	—	Arc color. Ignored when a threshold is active.
`thresholds`	`ThresholdSpec[]`	❌	`[]`	Color thresholds. Each overrides `gaugeColor` in its range.
`thresholds[].value`	`number`	✅	—	Threshold upper bound.
`thresholds[].color`	`ColorSpec`	✅	—	Arc color for this zone.
`gaugeBackgroundColor`	`ColorSpec`	❌	White low opacity	Background arc color (full track).
`glowColor`	`ColorSpec`	❌	—	Glow color. Required if `showGlow` is true.
`valueTextColor`	`ColorSpec`	❌	Fill #FFF	Center text color.
`tickColor`	`ColorSpec`	❌	Fill #FFFFFF66	Tick color (if `showTicks` is true).
`gapAngle`	`number`	❌	`120`	Bottom gap in degrees. 0 = full circle, 120 = tachometer, 180 = semicircle.
`lineWidth`	`number`	❌	`14`	Arc thickness in points.
`showTicks`	`boolean`	❌	`false`	Graduation ticks.
`showGlow`	`boolean`	❌	`false`	Glow on the arc.
`label`	`string`	❌	null	Text below value (e.g. `"CPU"`).
`unit`	`string`	❌	null	Unit inline with value (e.g. `"%"`, `"°C"`).
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

unit is rendered inline with the value (e.g. 72%); label is a separate descriptive line below (e.g. CPU).

7. RadialGaugeLarge

type: "RadialGaugeLarge" 2×1

2 or 3 side-by-side radial gauges on a single 2×1 widget with a shared title. Omit gauge3 for a 2-gauge layout.

Example Response (3 gauges)

{ "name": "System Status", "type": "RadialGaugeLarge", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "gauge1": { "value": 72.0, "minValue": 0.0, "maxValue": 100.0, "thresholds": [ { "value": 40.0, "color": { "type": "Fill", "primaryColor": "#00FF00" } }, { "value": 80.0, "color": { "type": "Fill", "primaryColor": "#FF8C00" } }, { "value": 100.0, "color": { "type": "Fill", "primaryColor": "#FF0000" } } ], "gaugeColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "gaugeBackgroundColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "valueTextColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "gapAngle": 120, "lineWidth": 14, "label": "CPU" }, "gauge2": { "value": 45.0, "minValue": 0.0, "maxValue": 100.0, "gaugeColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "gaugeBackgroundColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "valueTextColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "gapAngle": 120, "lineWidth": 14, "label": "RAM" }, "gauge3": { "value": 55.0, "minValue": 0.0, "maxValue": 200.0, "gaugeColor": { "type": "Gradient", "primaryColor": "#FF8C00", "secondaryColor": "#FF0000" }, "gaugeBackgroundColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "valueTextColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "gapAngle": 120, "lineWidth": 14, "label": "Disk" }, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`gauge1`	`GaugeSpec`	✅	—	Left gauge. Same schema as RadialGauge payload, without nameFont/namePosition.
`gauge2`	`GaugeSpec`	✅	—	Center (3 gauges) or right (2 gauges).
`gauge3`	`GaugeSpec`	❌	null	Optional right gauge. Absent = 2-gauge layout.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Shared widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

GaugeSpec fields: value ✅, minValue ✅, maxValue ✅, gaugeColor ✅, thresholds ❌, gaugeBackgroundColor ❌, glowColor ❌, valueTextColor ❌, tickColor ❌, gapAngle ❌, lineWidth ❌, showTicks ❌, showGlow ❌, label ❌, unit ❌.

8. CircularProgress

type: "CircularProgress" 1×1

Full 360° progress ring (0.0–1.0). Center text with optional caption. For goals, battery, download progress, or any percentage metric.

Example Response

{ "name": "Goal Completion", "type": "CircularProgress", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "progress": 0.72, "label": "72%", "ringColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#0000FF" }, "ringBackgroundColor": { "type": "Fill", "primaryColor": "#FFFFFF26" }, "valueColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "caption": "Goal", "captionPosition": "below", "captionColor": { "type": "Fill", "primaryColor": "#FFFFFF99" }, "lineWidth": 14, "showValue": true, "showGlow": false, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`progress`	`number`	✅	—	Progress value 0.0–1.0.
`ringColor`	`ColorSpec`	✅	—	Progress arc color.
`label`	`string`	❌	null	Center text. If absent, auto-percentage shown.
`ringBackgroundColor`	`ColorSpec`	❌	White low opacity	Background ring (full 360°).
`valueColor`	`ColorSpec`	❌	Fill #FFF	Center text color (if `showValue` is true).
`caption`	`string`	❌	null	Secondary text adjacent to value.
`captionPosition`	`"above" \| "below"`	❌	`"below"`	Caption position relative to value.
`captionColor`	`ColorSpec`	❌	White low opacity	Caption color.
`lineWidth`	`number`	❌	`14`	Ring thickness in points.
`showValue`	`boolean`	❌	`true`	Show center text.
`showGlow`	`boolean`	❌	`false`	Glow on the arc.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

9. KPIMetric

type: "KPIMetric" 1×1

KPI value with unit, trend indicator (up/down/neutral + percentage), and embedded sparkline. Designed for at-a-glance monitoring of a single key metric.

Example Response

{ "name": "Steps Today", "type": "KPIMetric", "version": "1.0", "refreshInterval": 30, "backgroundColor": { "type": "Fill", "primaryColor": "#1A1A2E" }, "backgroundType": "ROUND_RECT", "payload": { "value": 8432.0, "unit": "steps", "trendPercentage": 12.3, "trendDirection": "up", "sparklineValues": [3200, 4100, 3800, 5600, 6200, 7400, 8432], "valueColor": { "type": "Fill", "primaryColor": "#FFFFFF" }, "trendUpColor": { "type": "Fill", "primaryColor": "#00FF00" }, "trendDownColor": { "type": "Fill", "primaryColor": "#FF0000" }, "sparklineColor": { "type": "Gradient", "primaryColor": "#00FFFF", "secondaryColor": "#00000000" }, "isInt": true, "showSparkline": true, "showGlow": false, "nameFont": { "font": "Lato-Regular", "color": { "type": "FILL", "color": "#FFFFFF" } }, "namePosition": "TOP_LEFT" } }

Payload Fields

Field	Type	Req	Default	Notes
`value`	`number`	✅	—	Primary KPI value.
`valueColor`	`ColorSpec`	✅	—	Primary value text color.
`unit`	`string`	❌	null	Unit of measure (e.g. `"km"`, `"bpm"`, `"°C"`).
`trendPercentage`	`number`	❌	null	Absolute percentage change.
`trendDirection`	`"up" \| "down" \| "neutral"`	❌	`"neutral"`	Trend direction. Required if `trendPercentage` is present.
`sparklineValues`	`number[]`	❌	`[]`	Historical values for sparkline (min 2). Required if `showSparkline` is true.
`trendUpColor`	`ColorSpec`	❌	—	Color for upward trend. Required if direction can be `"up"`.
`trendDownColor`	`ColorSpec`	❌	—	Color for downward trend. Required if direction can be `"down"`.
`sparklineColor`	`ColorSpec`	❌	—	Sparkline color. Required if `showSparkline` is true.
`isInt`	`boolean`	❌	`false`	Display value as integer (no decimals).
`showSparkline`	`boolean`	❌	`false`	Show embedded sparkline.
`showGlow`	`boolean`	❌	`false`	Glow on sparkline.
`nameFont`	`FontModel`	❌	Lato-Regular #FFF	Widget title.
`namePosition`	`string`	❌	`"TOP_LEFT"`	Title position.

Widget Type Summary

`type`	iOS DTO	Size	Description
`BarChart`	`BarChart2x1DTO`	2×1	Vertical bar chart with highlight
`PieChart`	`PieChartDTO`	1×1, 2×1	Pie or donut with optional legend
`AreaChart`	`AreaChart2x1DTO`	2×1	Area chart with gradient fill
`TimeSeriesLineChart`	`TimeSeriesLineChart2x1DTO`	2×1	Time series line with optional grid
`StackedBarChart`	`StackedBarChart2x1DTO`	2×1	Multi-series stacked bar
`RadialGauge`	`RadialGauge1x1DTO`	1×1	Arc gauge with thresholds
`RadialGaugeLarge`	`RadialGaugeLarge2x1DTO`	2×1	2 or 3 side-by-side gauges
`CircularProgress`	`CircularProgress1x1DTO`	1×1	360° progress ring
`KPIMetric`	`KPIMetric1x1DTO`	1×1	KPI with trend and sparkline