Field types

Coercion#

POST /v1/integrations/{slug}/fields accepts a JSON object {"key": value}. Each value is coerced to the type you declared in the editor. If any value fails validation — the entire request is rejected (422 invalid_fields) with an error text for each field.

sparku push supports two assignment syntaxes:

• field=value — sends a string, the server coerces it to the field type;
• field:=json — sends the value as is, parsed as JSON (items:='[{"title":"a"}]', done:=true, state:=null).

null (via field:=null) clears a field without removing it from the schema.

Type table#

Type	Value in push	Coercion from CLI string	Note
text	"prod"	taken as-is	truncated to length limit (default 120 chars), not rejected
number	72	Double(string)	unit, min/max for scales and rings; accumulated for graph history
progress	0.7	number 0…1, or "70%"	strictly 0…1 after coercion
bool	true	true/false/yes/no/on/off/1/0 (case-insensitive)	for toggles and equalizer
state	"failed"	string, must be in the field's state list	each state has icon, color, animation, flash on transition
time	ISO 8601 or +5m	+5m, -1h30m, ISO 8601	timers tick inside SparkU — no need to push every second
image	path or base64 (≤ 256 KB)	path /… or ~/…, or base64 (can have data:...,)	PNG/JPEG only
url	"https://…"	string with scheme	for button actions; javascript: and data: rejected
list	[{"title": "…"}]	only field:=json	up to 50 rows

Push examples for each type#

sparku push deploy title="Production deploy"
sparku push server cpu=37.5
sparku push build progress=70%          # equivalent to progress=0.7
sparku push server ready=true
sparku push build stage=failed          # value must be declared in the field
sparku push timer ends=+5m              # 5 minutes from now
sparku push timer ends=2026-10-01T12:00:00Z   # ISO 8601
sparku push now cover=~/cover.png
sparku push deploy link=https://ci.example.com/builds/482
sparku push queue items:='[{"title": "Build"}, {"title": "Tests", "state": "running"}]'

Time format#

One of the following is accepted:

• Relative offset from now: +5m, -1h30m, +90s, +2d. Units are d, h, m, s, can be combined but only in decreasing order (1h30m, not 30m1h). A single time field works as both a timer (+5m — countdown) and a stopwatch (-10m — elapsed time).
• ISO 8601 with time and timezone (2026-10-01T12:00:00Z, with fractions of a second too).
• UNIX time — only as a number in field:=1699999999, not as a string in field=….

list — row objects#

Each element is an object {"title", "subtitle"?, "value"?, "state"?, "icon"?} or just a string (becomes title). Only title is required. At most 50 elements per write.

sparku push queue items:='[
  "Simple string",
  {"title": "Build", "subtitle": "main", "state": "running"},
  {"title": "Tests", "value": "42/50", "icon": "checkmark"}
]'

image#

• Absolute path (/Users/…) or path with ~ — file must exist and be PNG or JPEG.
• Or content in base64 (can have prefix data:image/png;base64, — it's discarded). Limit — 256 KB after decoding; larger is rejected.

Error texts for 422 (from code)#

The 422 invalid_fields response contains fields: [{field, message}], and the combined message is field: message; field2: message2. Examples of real texts:

progress: expected 0…1, got 70
progress: expected number 0…1, got "many"
cpu: expected number, got "abc"
ready: expected true or false, got "maybe"
stage: expected one of: queued, running, passed, failed; got "cancelled"
ends: expected time (ISO 8601, +5m, -1h30m, or UNIX time), got "tomorrow"
cover: file not found: /Users/me/cover.png
cover: only PNG and JPEG are supported
cover: base64 not parsed or image larger than 256 KB
link: expected URL with scheme (https://…), got "example.com"
link: scheme "javascript" is not supported
items: expected array, got object
items: at most 50 rows, got 63
items[0]: no title
title: expected string, got array

Error for an undeclared field:

field not declared in integration "deploy"; available: title, progress, stage
field not declared: integration "deploy" has no fields yet

Both texts appear in the API response and in the integration log in Settings.