app/docs/reference/payload-types.md

Payload types

Every port declares a dtype. Fluksio checks values against it and offers compatible messages when you bind dashboard widgets.

Messages carry JSON. Binary data lives in the artifact store; messages carry references to it.

Scalars

dtype	Accepts
float	integer or floating-point number, excluding booleans
int	integer, excluding booleans
str	string
bool	true or false

NaN and infinity are rejected, including in structured payloads. For an unavailable numeric result, omit that output or return None to publish nothing. A numeric port does not accept None as its value.

Structured payloads

record

An object with string keys and scalar or null values. Nested objects and lists are not allowed.

{"title": "Boiler", "body": "Pressure low", "severity": "warning"}

Notification and Player widgets read records. Dashboard alert channels also publish them.

list

An array with a declared item type:

item	Accepts
unset or record	flat records; used by Agenda and Forecast
float, int, str, bool	scalars of that type
json	arbitrary JSON values

list and series cannot be declared as item types. Use item: "json" if items need arbitrary nested structures.

series

Labelled lines of numeric [timestamp, value] pairs:

{
  "lines": [
    {"label": "living", "points": [[1717000000, 21.4], [1717000060, 21.5]]}
  ],
  "range_s": 86400,
  "interval_s": 60
}

Additional top-level keys are preserved. A Query chart expects the range_s and interval_s from its request in the response; this prevents an answer for another window from replacing its chart.

The run-series comparison endpoint also returns this shape.

artifact

A reference to bytes in the content-addressed artifact store:

{"digest": "sha256:…", "size": 4194304, "media_type": "application/octet-stream", "name": "weights.pt"}

digest and size identify the content. media_type and name describe it. The reference works wherever the store is reachable.

Create one with fluksio.save_artifact and read its bytes with fluksio.load_artifact. See Artifacts.

image, audio, video

Artifact references restricted to the matching media_type family:

{
  "digest": "sha256:…",
  "size": 61344,
  "media_type": "image/jpeg",
  "name": "frame.jpg",
  "meta": {"width": 1280, "height": 720, "seq": 41}
}

An audio port accepts audio/*; image and video work the same way. An artifact port accepts all three. Optional meta fields are for the consumer; Fluksio does not interpret them.

A media stream is a streaming port publishing one reference per frame or chunk. Saving with volatile=True keeps bytes in memory and lets local websocket clients receive them with the value. Stored media and portal views fetch the bytes separately.

Use occasional snapshots through a portal. For continuous video, point a Media widget's Live stream at a browser-compatible source URL reachable by the screen.

json

Any JSON-serializable value. Use it for payloads without a fixed shape. Prefer a specific type when one fits; it gives widgets and other authors a clearer contract.

Referencing a run's output

A run parameter can name an existing value instead of repeating it:

• @run:<id>.<output> resolves an earlier run's output.
• sha256:… resolves an artifact digest.

These strings resolve before the run starts, regardless of the input's type. Both prefixes are reserved even for str inputs; they cannot be passed as literal text in run parameters.

Widget bindings

Widget	Accepts
Gauge, live Chart, Slider, Bar, Counter	float, int
Query Chart	series response, record request
Switch	bool
Agenda, Forecast	list
Notification, Player	record
Colour	list for HSV/RGB, str for hex
Media	image, audio, video, artifact
Value, Icon, Button, Buttons, Input, Selector	no fixed type restriction
Clock, Text, Website	no message binding

Player transport commands publish to a separate str message. Binding checks apply in the editor and on the server.

Icon and colour names

Forecast reads a list of records with label, icon and value, plus optional color:

[{"label": "Today", "icon": "cloud-rain", "color": "primary", "value": "14°"}]

The Icon widget uses the same vocabulary:

	Names
Icons	sun, moon, cloudy, cloud-rain, cloud-drizzle, cloud-snow, cloud-lightning, cloud-fog, wind, umbrella, snowflake, droplets, thermometer, thermometer-sun, flame, fan, sun-snow, door-open, house, bed, lightbulb, plug, cctv, music, volume-2, volume-x, zap, battery-charging, arrow-up, arrow-down, triangle-alert, check, circle-check
Colours	default, muted, primary, success, danger

An empty icon draws nothing. Unknown icons use a placeholder; unknown colours use default. Each warns once in the browser console.

Type failures

A mismatched value raises an error on the node that produced it, naming the port and received value. It is not published downstream.

See also

• Flows, nodes and messages
• Node types
• Dashboards and panels