Data Sources

warning

Experimental. This feature may change or be removed.

A Custom Dashboard may bind one data source, or none. The host resolves data on the server and posts the result into your shell. The page never runs free-form SQL and never receives a token for that purpose.

Open Data source from the gear menu (Custom Dashboard only).

Source types

Kind	What you configure	What the host fetches
None	Leave unbound	source is null; theme still arrives after ready. Good for static HTML.
TagoSQL	One saved query	Server executes that stored query.
API (GET URL)	One URL template	Server performs a GET only after expanding allowlisted placeholders.

Only one of these can be active at a time.

TagoSQL source

1. Create and save a query under TagoSQL if you do not have one yet.
2. In Data source, choose TagoSQL and pick the saved query.
3. Optionally map query parameter names (for example $1) to host-context keys so each load injects the current profile, dashboard, or user values.

If you add no parameter map, the query runs with its stored defaults.

Parameter mapping is for the saved query's placeholders. It is not free-form SQL from the browser.

API (GET URL) source

Choose API (GET URL) and enter a URL template. The server expands {{...}} placeholders, then issues a GET. Other HTTP methods are not supported.

Example:

https://example.com/api/report?user={{user.id}}&dashboard={{dashboard.id}}

Placeholders must be allowlisted host-context keys (below). Unknown keys are rejected when you save.

For the API path, host context expands directly in the URL template. The TagoSQL-style parameter map is not used for API sources.

Host-context keys

These keys can appear in URL templates as {{key}}, or as values in the TagoSQL parameter map:

Key	Meaning
profile.id	Current profile id.
account.id	Account id.
dashboard.id	This dashboard's id.
user.id	Signed-in user id when available.
user.name	User display name when available.
user.email	User email when available.

User fields depend on the signed-in session. Design URL templates and queries so missing user fields do not break the page if your flow can load without them.

What the shell receives

After your page posts dashboard:ready, the host loads data and posts dashboard:data with:

{
  "type": "dashboard:data",
  "source": { "kind": "tagosql", "query_id": "..." },
  "data": {}
}

• source describes the bound configuration, or is null when no source is set.
• data is the resolved payload (query result or GET response body as returned by the server). Shape depends on the source; treat it as application-specific and validate in your page.

Refresh from the dashboard header re-runs this path without reloading the HTML shell.

API surface (data)

Admin uses:

POST /dashboard/{id}/data

with a profile token. The response shape is { source, data }. See the TagoIO API reference for the full response schema.

Setup (which source is bound) is stored on the dashboard via the normal dashboard edit API (setup field), usually through the Data source dialog.

Limits of the model

• One optional source per dashboard.
• No client-authored SQL, no multi-source merge in the host, no device-variable picker like widgets.
• For multi-source or realtime widget behavior, use a Normal or Blueprint dashboard with Custom Widgets instead.