/v1/dashboards), with the same session token the widget holds, so
your product renders them wherever it wants.
How the pieces fit
What a dashboard is made of
Filters are the controls on the page: adate_range (with a preset
default such as “last 30 days”, so a refresh stays relative), a select
(a property, a store, a team), a text, number or date. Source arguments
read them as {{filters.<key>}} — {{filters.<key>.from}} and .to for a
range.
A select lists its options in options, or reads them from a source with
options_from: { source, value, label } — the source’s rows at each refresh
become the choices (value and label are field paths into a row). Such a
source must not read a filter itself. The read model returns the resolved
list as options, so the page renders one kind of select, and a spec with
options_from works for a user whose option list differs — what makes a
dashboard copied from a template fit its new owner. Give such a select no
default and it starts on the row options_from.default flags — a field path,
e.g. "default": "is_default": the first row where it is truthy — else on the
first option. The refresh reads its source before the other sources, a
value that is not one of the options falls back to that start value, and the
read model returns it in filters.values so the page shows it selected.
Sources are the data: one entry per tool call, with the tool’s arguments
and, when it paginates, a loop (all_pages, fields to keep, a row
filter, and a cache TTL — see below). Several panels can read one source.
Panels are what is shown, in order, on a 12-column grid. Each has a
span (3, 4, 6, 8 or 12 columns) and a height (sm, md, lg).
A panel’s kind names the component that renders it, and
every component is a kind: stats, chart, table, calendar, image,
image_gallery, link_preview, code_block, code_diff, message_draft,
weather — the component’s tool name without show, in snake case, so a
component added to the contract is a panel kind at once. A data panel names
its sources and carries a transform: a few lines of JavaScript that turn
the sources’ raw output into the panel’s payload — exactly the payload of
that component (showStats, showChart, showTable, showCalendar, …),
so the SDK renders a panel with the same code it renders a chat answer with.
text panels carry markdown and no transform.
How the agent builds one
The dashboard agent never guesses a field name. It lists the read-only tools of the network (list_source_tools), reads a tool’s arguments
(describe_source_tool), runs the sources for real with the filters
resolved (preview_dashboard_sources) and writes each transform against the
output it saw. It knows the payloads of stats, charts and tables by heart and
reads any other component’s schema with describe_panel_kind before writing
a transform for it (“use the calendar component for the arrivals” is a
calendar panel, not a search of the source tools). save_dashboard then compiles the spec, runs a full test
refresh, and publishes a version only when every panel rendered; a failed
test hands the agent the failing step with the data it received, so it fixes
the transform and saves again. The user sees a dashboard only once a refresh
has succeeded.
Only read-only tools qualify as sources: a custom API tool whose
read_only flag is true, or —
when the flag is not set — one with a GET method, or any other method
under a name that reads as one (list_, search_, get_… — a
POST /reservations/search named “List reservations” is a source; the same
method under “Create reservation” or a name with no verb is an action, and
so is a tool flagged false whatever its name); an MCP tool whose server
marks it readOnlyHint (or whose name reads as one); a toolkit action with
a read verb. An API whose every endpoint is a POST under a bare name
(/rpc/my_stay) needs the flag set on its reads before the agent sees any
source. The only writes a dashboard can send are the ones its spec declares
as form views, each triggered by a person who
submits the form.
Drawers, modals and forms
A dashboard’s elements can be clickable. A stat tile, a table row, a button on a row or a button in the dashboard’s toolbar opens a view in a drawer (a panel on the left) or a modal:-
a detail view (
kindtable,stats,chart,calendaror any other component kind): a panel with a context — its own sources and transform, run on demand when the element is clicked, never at refresh time. A stat opens the rows behind the number; a row opens that record’s details. -
a form view (
kindform): one write, built from an action tool’s input schema. The page renders the form from the schema, the user fills it in and submits, the platform runs the tool once, and the dashboard refreshes. A row opens its edit form; a “New booking” button opens the create form. -
a thread view (
kindthread): a conversation held on the platform — the Mastra thread named by thethread_idcontext key — rendered with its messages, media and sender labels, plus a reply box when the view names areply_tool. The view’s trigger passes the thread id in the context ({ "thread_id": "{{row.thread_id}}" }), and the page reads the thread throughGET /v1/dashboards/{id}/views/{viewId}/messages?thread_id=…&copilotId=…(the body ofGET /v1/messages). The viewer’s own threads are served asGET /v1/messagesserves them. Any other thread of the organization — an inbox shows conversations held by a service user — is served only when the network’ssystem_agents.dashboard.thread_access_tool(set on the copilot named bycopilotId, never in the spec) answerstrueor{ "allowed": true }for it: the platform runs that source tool in the viewer’s session with the thread id, so the consuming application decides who may read which conversation. Reading never marks the thread read. A reply is one run of the reply tool with the typed text inreply_field(defaulttext) andreply_fixedsent as-is — usually{ "thread_id": "{{context.thread_id}}" }— followed by a refresh; it compiles and runs exactly like a one-field form, soPOST …/views/{viewId}/runtakesvalues: { text }. Withoutreply_toolthe view is read-only (read_only: trueon the read model) and has nothing to run. This is what a unified inbox is: a table overconversationswhose row click opens the thread.
spec.views; what opens them are triggers: a stats
panel’s on_click (every tile, or the keys listed in stats), a table
panel’s cell_triggers (by column key: the cell’s value is drawn as a link
and opens the view, so the company name opens the company card and the
dossiers count opens the dossiers), on_row_click (the whole row opens one
view; never together with cell_triggers) and row_actions (buttons at the
end of every row, for an action such as a form; the panel names its
row_key), and the dashboard’s actions (toolbar buttons). A
trigger is { view, context }: context maps the view’s context keys to
what the click offers — {{row.<field>}} or {{row}} on a table row,
{{stat.key}} / {{stat.value}} on a tile, {{filters.<key>}} anywhere —
or to literals. The page resolves the templates and runs the view with the
result.
context keys it takes ({{context.<key>}} in
its sources’ args, input.context.<key> in its transform); a source that
reads a context is view-only. A form view names its tool (an action
tool: a custom API tool with a write method, an MCP tool or toolkit action
with a write verb or annotation — the dashboard agent lists them with
list_action_tools), the fields the user fills in, fixed parameters
sent as-is (the record id from the context, a constant, a filter value) and
initial values for the editable fields. Every required parameter of the
tool is in fields or fixed. A tool the chat requires approval for makes
the form ask for a confirmation before it sends.
Each view compiles to its own workflow, saved with the dashboard’s version.
The save-time test runs every detail view once with its sample_context
and the filters the page opens on (a select with options_from and no
default takes the value the test refresh started it on); forms are checked against the tool’s schema, never executed. Because a view
runs only when clicked, a broken drill-down never fails the refresh.
A view’s sources should be narrowed by the click whenever the tool allows it
({{context.id}} as an argument). When a view has to read the same long
walk the dashboard itself reads, give that source a loop.cache
({ "ttl_minutes": 1440 }): the refresh always walks upstream and stores the
set, and the view is served from that store within the TTL, so the click
answers in well under a second with the rows the dashboard is showing
instead of walking the collection again. A source narrowed by the context
needs no cache.
The read model carries the views on spec.views; a form view also carries
schema, the JSON Schema of its fields, which is what a page renders. A
view runs through one call:
POST /v1/dashboards/{id}/refresh and force: true (so a refresh started
moments before the write is not reused). 422 means the context or the
values do not fit the view (issues[] says what). A view run is listed under
the dashboard’s workflow like a refresh (GET /v1/dashboards/{id}/runs/{runId}
answers with view instead of data), with the user’s own credentials, the
usage gate and a run row — the dashboard’s “last refreshed” state is not
touched.
Talking about a dashboard
The roster answers every turn, as on any other.mode: "dashboard" on the
turn marks a conversation of the Dashboards section (the new-dashboard view,
or an open dashboard); it changes who the thread belongs to, never who
answers.
When the user has a dashboard open, send its id as dashboardId on the chat
turn (with the network’s copilotId). The agent that answers gets the
dashboard’s header in context — name, version, filters, last refresh and the
panel list — and a read_dashboard tool for that turn. A question about its
numbers (“what stands out this week?”) makes the agent read the current data
first, so it answers from the same numbers the user is looking at; a turn
about anything else carries the header only, not the data. A change
(“make the chart wider”, “add occupancy next to revenue”) it hands to the
dashboard agent with that dashboard’s id and the user’s words, and relays the
report once the new version is saved.
dashboardId, so follow-ups in the same thread
need no id, and GET /v1/threads?dashboardId=… lists the conversations about
one dashboard (the widget’s “previous conversations”). A conversation started
in the Dashboards section (mode: "dashboard") that BUILDS a dashboard is
stamped with it too, so the new-dashboard view’s chat becomes that dashboard’s
conversation. A dashboard built from an ordinary roster conversation — “save
this as a dashboard” at the end of a chat about an automation — is not tied to
that thread: the user opens the dashboard and talks to it in a conversation of
its own.
The dashboard agent’s model and extra instructions are set per network under
system_agents.dashboard — see the platform agents;
enabled: false there removes it from every roster agent of the network.
Names in, ids stored
A spec names its tools the way the agent sees them (pms_list_reservations).
What the platform stores and trusts is the stable reference behind each
name: every save writes a tool_ref next to each source’s tool and each
form’s tool (a tool row id, or an MCP provider id plus tool name), and the
compiled workflow runs on those ids, so a rename never breaks a refresh. On a
later save the name is resolved first; when it no longer exists, the ref
stored behind the same source id is used instead, so a renamed tool is
invisible to whoever edits the dashboard. Only a tool that was removed fails
the save, with an issue naming the source and the catalogue to pick from.
The agent never sees the refs; a read over HTTP returns them so a copy keeps
them, and POST /v1/dashboards accepts a spec with or without them.
Creating a dashboard from a spec
A starter dashboard should be a copy, not a model run.POST /v1/dashboards
takes { network_id, environment, spec }, where spec is the spec object
a dashboard read returns (not the whole read model) or a template’s, and
creates the dashboard for the caller’s user: compiled, test-refreshed with
the caller’s credentials, published as version 1 and activated — the
dashboard agent’s save path without the agent. The network is named by its
id (GET /v1/networks) and the environment (dev, staging, prod): a
network has exactly one copilot per environment, so moving the same call
from staging to production is a one-word change. Sources and actions name
tools by their agent-facing name and are resolved against that copilot’s
catalogue (the read-only tools of its agents are sources, its write tools
actions); a tool the copilot does not carry fails the call with 400 naming
it, and a spec whose first refresh fails answers 422 with the step reports.
A network with no copilot for that environment is a 404. A session creates
for its own user; an API key names the user with X-User-Id.
Templates on the empty state
The widget’s “New dashboard” empty state callsGET /v1/dashboards/templates?copilotId=… and shows the cards it returns —
[{ key, title, description, icon, spec }], each spec ready for
POST /v1/dashboards. Cards are plain text, no markdown; an empty list shows
only the prompt.
The cards come from the organization’s dashboard template store
(/v1/dashboard-templates), one template per key:
- Shared templates. The platform organization’s templates are offered to
every organization. A repository publishes its set from CI with
POST /v1/dashboard-templates/publish(only the templates whosehashchanged, the full list ofkeysfor the order, acollectionper publisher so two publishers never retire each other’s keys);GET /v1/dashboard-templates/stategives the hashes to diff against. - Your own templates and overrides.
PUT /v1/dashboard-templates/{key}writes a whole template for your organization — on the key of a shared one, it replaces it for you.PATCHchanges some fields; on a shared template it stores an override holding just those, so the rest keeps following the shared one:{ "enabled": false }hides a shared template,{ "tags": [...] }changes who sees it.DELETEremoves your row and the shared one is offered again.GET /v1/dashboard-templates?scope=effective|org|sharedlists them (include_spec=truefor the specs). - Audience. A template’s
tagsare matched against the tags of the network behindcopilotId(tagsonPOST/PATCH /v1/networks): a template with tags is offered on a network sharing one of them, a template without tags on every network. A consuming app that runs one network per role tags each network with the role (general_manager) and with the permissions that matter (users.manage), and its templates with the same words. - Per caller. A spec is the same for everyone; what differs per user comes
from the user’s own session at run time. A
selectwithoptions_fromand nodefaultlists the caller’s own values and starts on the flagged or the first one (see Filters above).whenhides a template unless a read run in the caller’s session yields enough values — the spec’s own select ({ "filter": "property", "min_options": 2 }) or a source tool named outright ({ "tool": "list_property_options", "value": "id", "min_options": 2 }): a portfolio page only for someone with several hotels. The read runs once per picker load, whatever the number of templates naming it.
system_agents.dashboard.templates_tool gets the cards of that
tool, run in the user’s session, as before; the field is then removed. When
that tool is gone, fails or answers something other than cards, the picker
returns no templates (the empty state still lets the user describe a
dashboard) rather than an error.
Who may read a thread view’s conversation
A thread view can open a conversation the viewer does not own: an inbox of guest conversations held by the organization’s liaison service user. The network decides who may read those, never the dashboard: name a source tool insystem_agents.dashboard.thread_access_tool (PATCH /v1/copilots/{id}). When
the viewer is not the thread’s owner,
GET /v1/dashboards/{id}/views/{viewId}/messages runs that tool in the
viewer’s session with the thread id under the tool’s first required
parameter (thread_id when it declares none), and serves the messages only
when it answers exactly true or { "allowed": true }. Anything else, an
error included, is a 403, and so is a network that names no tool.
From any agent in the roster
The user does not have to open the Dashboards section to get a dashboard. Every agent of the network has the dashboard agent as a sub-agent: when the conversation turns into “make me a dashboard of this”, the agent delegates with a brief — what to show, the period, the filters and breakdowns the conversation settled on, the tools and parameters behind the data, the user’s language. The dashboard agent does not read the conversation (a long thread re-sent on every build would cost more than it tells), so the roster agent is told to make the brief complete. What it gets besides the brief is the user’s own last message, verbatim — padded with the messages before it when it is short, clipped when it is long — which sets the language of its report and the dashboard’s titles; the brief’s language, then theuser.language variable
when the host app sends one, are the fallbacks. The dashboard the user is
looking at reaches it through the dashboardId of the turn. It lists and previews the sources, builds, tests and saves
the dashboard, and reports back in a few sentences; the roster agent relays
them.
The delegation streams: the dashboard agent’s steps appear nested under the
roster agent’s tool call while it works. When a dashboard is saved, the
platform appends its link — [name](sidenet://dashboard/<id>) — to the
report the roster agent receives, with the instruction to end its answer with
that link; the chat widget renders the link as the dashboard card (the name,
the version, the panel count and an Open button that opens the dashboard
in the Dashboards section), and renders the card itself at the end of the
answer when the agent left the link out. With a dashboard_id in the brief, the delegation changes an existing dashboard
instead (a new version).
The same link ends the results of a scheduled automation that carries the
dashboard: the schedule’s dashboard_id (the widget’s “Dashboard” select on
the schedule form, or the dashboard page’s “Schedule” button) makes the
platform append [name](sidenet://dashboard/<id>) to every successful run’s
result — in the result conversation, and in the text a delivery tool
receives. See Linking a dashboard to the results.
A build takes one to several minutes and is a delegation like any other for
the agent that made it: it relays the dashboard agent’s two-sentence report
and ends with the link. Every agent on a network conversation knows the
dashboard agent from its description: when to delegate (the user asks for a
dashboard or a page to come back to; alerts and scheduled reports are
automations) and what a brief holds. When an answer rendered data components
(a chart, a table, a stats strip) and no dashboard was built in that turn,
the follow-up suggestions may include one that saves what was shown as a
dashboard, addressed to the agent that answered — tapping it is what triggers
the build, with a brief describing exactly what was shown. Outside a
network (no copilotId), or when the network switched its dashboard agent
off, no roster agent has the dashboard agent and answers with its
rendering components instead.
Rendering and refreshing
GET /v1/dashboards/{id} returns everything a page needs: the spec (filters,
panels, their span, height and order), the filter values to open on, and
data — the latest refresh with each panel’s rendered payload
(panels[].component.args is the showStats / showChart / showTable
input) or its markdown.
wait: true answers once the
run is over instead of 202. A refresh with the same filters started moments
ago is joined rather than started again (force: true starts a new one
anyway — after a form view wrote something). The workflow.run.finished
event on GET /v1/events fires when a refresh (or a view) ends. Dashboard
runs are left out of the org’s run log (GET /v1/workflow-runs) unless
the dashboard’s workflow is named with workflowId.
Insights
A spec may declare insights — the assistant’s reading of the data, written at every refresh and shown by the page:scope says where the page shows it: { "page": true } is a banner under
the header, closed to its headline; { "tab": { "group", "id" } } the same
banner under the tab bar of a page tab group while that tab is open;
{ "panel": "<id>" } a sparkle on the panel’s card whose popover holds the
text. sources are the sources the step reads (their rows, trimmed; a panel
insight also receives exactly what the panel draws), prompt the brief. Each
insight is one model call per refresh (DASHBOARD_INSIGHT_MODEL, else the
workflow default): the compiled refresh runs, after the renders, an input
step and an agent step per insight and a collect step last, so the answers
are the run’s output and come back under data.insights:
panel (and a stats tile’s stat) it is about, so
the page can point at it; actions are follow-up prompts for the dashboard’s
assistant. A failed step never fails the refresh: the entry comes back with
status: "failed" and its error. Two to five insights on a dashboard —
one for the page, one per analytical tab, a panel’s own only where that panel
is what people come to check — never one per panel.
GET /v1/dashboards/{id}/versions lists what the chat published;
POST /v1/dashboards/{id}/activate goes back to one of them and refreshes
it. PATCH /v1/dashboards/{id} renames the dashboard and / or sets its icon,
and returns it: send { "name": "…" } (1 to 120 characters), { "icon": "📊" }
or both; { "icon": null } removes the icon. The icon is one emoji (a single
emoji character — skin tones, flags, keycaps such as 1️⃣ and joined emojis
such as 👩💻 count as one), shown before the name in the Dashboards list, its tooltip and the page
title; text or two emojis answer 400 with “icon must be one emoji”. Both
belong to the dashboard, not to a version, so no version is published and a
later edit from the chat that does not itself rename the dashboard keeps the
name (the icon is never part of the spec). The list and the read return
icon (null when there is none); POST /v1/dashboards takes an optional
icon too, and the dashboard agent picks one fitting emoji for each
dashboard it creates. DELETE /v1/dashboards/{id} removes the dashboard.
Pinned dashboards
A person can pin dashboards: the SDK shows them above the Dashboards list, in the order they chose (they reorder them by dragging), on every device.PUT /v1/dashboards/pins with { "ids": ["…", "…"] } pins those dashboards in
that order and unpins every other one of the user’s — send the whole order
each time, so pinning, unpinning and reordering are each one call, and
{ "ids": [] } unpins all. The answer is { "pins": [...] }, the ids in order.
Every id must be one of the user’s dashboards: another user’s, a deleted or an
unknown one answers 404 naming it, and nothing changes; a repeated id or more
than 100 answer 400. A session sets its own user’s pins; an API key names the
user with userId (or X-User-Id). The list and the read return each
dashboard’s pin_position (0 for the first pinned, null when not pinned);
deleting a dashboard unpins it. Like the icon, the pins belong to the
dashboard, not to a version.
Refreshing after an agent writes
A dashboard shows the data of its last refresh. When a turn writes through a tool — an agent grants a role, checks a guest in, changes a rate — the data behind every dashboard reading that domain moves while the page keeps showing the old refresh. The API closes the gap in two ways, both at the end of the turn that wrote (a refresh started mid-turn would miss the later writes of the same turn):-
data_changed_aton every dashboard row (GET /v1/dashboardsand thedashboardobject ofGET /v1/dashboards/{id},POST /v1/dashboards,POST /v1/dashboards/{id}/activate): when a write last touched the sources this dashboard reads, or null. A dashboard is stale when it is later thanlast_refreshed_at(or when it was never refreshed) — refresh it withforce: truewhen it is opened. The stamp is never cleared; a successful refresh ends with a laterlast_refreshed_at, which is what the comparison reads. The SDK does this on its own. -
dashboard.data_changedonGET /v1/events, for the dashboard’s owner (and for the user who wrote, when they are someone else):One frame per affected dashboard; a burst of writes to the same dashboard within a second or two yields one frame. An open dashboard answers it with a forced refresh. Older clients ignore event types they do not know.
read_only: false (PATCH /v1/tool-providers/{id}/tools,
POST /v1/tools), else a write verb, a non-GET method or an MCP annotation.
It is matched against each dashboard’s sources by domain: the tags a
catalogue puts on its tools (team, housekeeping, front_desk, rates,
… next to read / write / approval). A dashboard is stamped when one of
its sources shares a domain with the write tool. When one side carries no
domain tag, the provider decides (same provider → stamped); a source whose
tool cannot be resolved to a provider at all (a static tool) is stamped by
every write — a refresh for nothing beats a stale page. Every write path
counts: a chat turn, a WhatsApp agent, a scheduled workflow or automation, a
sub-agent, an approved call executed later, POST /v1/tools/{id}/execute. A
call that failed, was declined or awaits approval does not. The one
exception is a dashboard’s own form (POST …/views/{viewId}/run): the
page refreshes that dashboard itself, so it is stamped but not told; the
other dashboards the form touched get both.
A refresh runs with the user’s own tool credentials, as a chat turn does —
the ones the session carries, or the ones captured when the dashboard was
saved. An API key refreshing on a user’s behalf names the user with
X-User-Id and may send runtimeAuth.