Skip to main content
A user asks the chat for “a dashboard of this month’s bookings by property, with revenue and occupancy”, and gets one: a grid of stats tiles, charts, tables (or a calendar of the arrivals, a gallery of the rooms — any component), fed by the data tools your agents already have, with a date-range and a property filter on top. They refresh it with a button, change a filter, ask for a change in plain words (“add a chart of cancellations”), and go back to an earlier version if the change was not what they wanted. No model runs when a dashboard refreshes: the agent builds it once; from then on it is a compiled workflow your API runs on request. The user asks the agents they already talk to; the platform’s dashboard agent does the building behind them, as a sub-agent of every roster agent, and the roster agent answers. The dashboards themselves are reachable over HTTP (/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: a date_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.
The platform compiles this to a workflow: a step that resolves the filters (date presets in the dashboard’s timezone), the sources in parallel, then each panel’s transform (in the code sandbox) feeding the rendering tool, whose own schema validates the payload. A refresh is a run of that workflow with the filter values as input; nothing in it calls a model.

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 (kind table, stats, chart, calendar or 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 (kind form): 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 (kind thread): a conversation held on the platform — the Mastra thread named by the thread_id context key — rendered with its messages, media and sender labels, plus a reply box when the view names a reply_tool. The view’s trigger passes the thread id in the context ({ "thread_id": "{{row.thread_id}}" }), and the page reads the thread through GET /v1/dashboards/{id}/views/{viewId}/messages?thread_id=…&copilotId=… (the body of GET /v1/messages). The viewer’s own threads are served as GET /v1/messages serves them. Any other thread of the organization — an inbox shows conversations held by a service user — is served only when the network’s system_agents.dashboard.thread_access_tool (set on the copilot named by copilotId, never in the spec) answers true or { "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 in reply_field (default text) and reply_fixed sent as-is — usually { "thread_id": "{{context.thread_id}}" } — followed by a refresh; it compiles and runs exactly like a one-field form, so POST …/views/{viewId}/run takes values: { text }. Without reply_tool the view is read-only (read_only: true on the read model) and has nothing to run. This is what a unified inbox is: a table over conversations whose row click opens the thread.
Views live in 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.
A detail view declares the 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:
The call answers when the view is over (no model runs). A data view returns the component to draw, in the same shape as a panel’s; a form returns the tool’s output, and the page then refreshes the dashboard with 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.
The thread is stamped with the 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 calls GET /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 whose hash changed, the full list of keys for the order, a collection per publisher so two publishers never retire each other’s keys); GET /v1/dashboard-templates/state gives 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. PATCH changes 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. DELETE removes your row and the shared one is offered again. GET /v1/dashboard-templates?scope=effective|org|shared lists them (include_spec=true for the specs).
  • Audience. A template’s tags are matched against the tags of the network behind copilotId (tags on POST / 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 select with options_from and no default lists the caller’s own values and starts on the flagged or the first one (see Filters above). when hides 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.
A write takes the organization’s API key (or a Studio user): templates are organization configuration. A session token reads the store and the picker.
Until the next release, a network the store offers nothing and whose copilot still names 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 in system_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 the user.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.
A filter change is a refresh with other values; 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:
A finding may name the 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_at on every dashboard row (GET /v1/dashboards and the dashboard object of GET /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 than last_refreshed_at (or when it was never refreshed) — refresh it with force: true when it is opened. The stamp is never cleared; a successful refresh ends with a later last_refreshed_at, which is what the comparison reads. The SDK does this on its own.
  • dashboard.data_changed on GET /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.
Which dashboards. A write is a successful call to a tool that writes — the catalogue’s 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.