widget

Call widget.add

Make a new widget on the desk or project the member is on — 'add a chart of our weekly visits', 'put a button here that refreshes the briefing', 'add a switch for the welcome automation to this desk'. A widget is a chart, a single number, a breakdown table, a monitor on one thing, a link straight back to a site, page, board or Data table, a note in their words, a button that presses one tool or starts one automation, or a switch that turns one automation on and off. It lands on the desk the call names, else the desk or project the member is on, else the Dashboard's first desk. For numbers, only call it when you know which numbers it shows and how far back it looks; if the ask is vague, ask one short question first. For one site or page use the site_* numbers with site_id (from page.list) or page_path. Never invent an id for a link, a button or a switch — read it from a tool that listed the thing. An expiry is a promise: pass expires_in_days when they said how long they want it. Not for a bespoke coded card — that is desk.build_card; not for showing an existing widget somewhere else — that is work.shortcut.

Every result names the workspace it ran in. Say which workspace the answer is about. When the account has more than one workspace and none is selected, this tool refuses with workspace_ambiguous and lists the choices — offer them, never pick one.

post/api/v1/tools/widget.add

Request

  • Base URL: https://app.goosybear.ai
  • URL: https://app.goosybear.ai/api/v1/tools/widget.add
  • Auth: HTTP bearer

Headers

x-request-idstring

Your own id for this request, echoed back and recorded on the audit trail. 1–128 characters from A–Z a–z 0–9 . _ : -, starting with a letter or digit; anything else is replaced by a generated id.

Idempotency-Keystring required

Your key for this write: send the same key when you retry and the first result comes back instead of a second action. Keys are honoured for at least 24 hours. 1–200 visible ASCII characters. Replaces the idempotency_key body field, which still works until 2026-12-31; this action needs a key on one of the two, and the header is the one to send.

Request body

board_idstring uuid

The desk or project it goes on, by its id (a desk's from widget.list, a project's from board.tree). Omit it for the desk or project the member is on.

kind'chart' | 'table' | 'kpi' | 'monitor' | 'note' | 'link' | 'button' | 'switch' | 'briefing' | 'needs_you' | 'analytics' required

chart for a trend over time · kpi for one number · table for a breakdown · monitor to watch one thing · link for a way straight back to a site, page, board or Data table · note for anything they want written down · button to press one tool or start one automation · switch to turn one automation on and off, or flip one yes/no cell of a Data table · briefing, needs_you and analytics for the week's briefing, what is waiting on them and their analytics panel.

titlestring required

What they will see on it. Plain business language, their words where you have them.

metric_keysstring[]

Which numbers it shows. Required on chart, table, kpi and monitor; omitted on every other kind.

grain'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'lifetime'

How the numbers are bucketed. Use 'day' for a chart unless they asked for weeks or months.

window_periodsinteger

How far back it looks, counted in grain periods. 'the last 28 days' with grain=day is 28.

compare'none' | 'previous_period' | 'same_period_last_year'

What it compares against. 'previous_period' is the usual answer; 'none' shows a bare number.

link_target_kind'page' | 'site' | 'board' | 'data_table'

For a link: what it opens — a site, a page, a board (or project), or a Data table. Required for that kind.

link_target_idstring

For a link: the id of the thing it opens, read from a tool that listed it — a link to an id that does not resolve is a dead widget.

note_bodystring

For a note: what it says, in their words where you have them. Markdown renders. Required for that kind.

site_idstring uuid

For site_* numbers only: narrow it to one of their sites, by its id from page.list — never an invented id. Add page_path for one page of it.

page_pathstring

For site_* numbers only: narrow it to one page by its path, like /pricing — that path on every site unless site_id is also given.

labelstring

For a button or a switch: the words on it.

press_toolstring

For a button that presses a tool: the tool's name, like 'briefing.regenerate'. Pressing it runs that tool behind the tool's own approval.

press_automation_idstring uuid

For a button that starts an automation: its id, read from a tool that listed it.

switch_automation_idstring uuid

For a switch that turns an automation on and off: its id, read from a tool that listed it.

switch_data_table_idstring uuid

For a switch on one yes/no cell: the Data table's id. Pass switch_row_id and switch_column with it.

switch_row_idstring uuid

For a switch on one yes/no cell: the row's id.

switch_columnstring

For a switch on one yes/no cell: the column's key.

expires_in_daysinteger

Take it down again after this many days. 'for two weeks' is 14. Omit for a widget that stands until they remove it.

idempotency_keystring

Deprecated on REST: send the Idempotency-Key header instead. Still accepted until 2026-12-31; if both are sent they must match.

workspacestring

Which workspace to run in — its slug. Omit to use your default. With more than one reachable workspace and no default, the call is refused and the choices are listed.

Response

The call was admitted and dispatched. ok says whether the tool succeeded — a refusal the tool itself produced is still a 200, exactly as it is a successful JSON-RPC result over MCP.

OR

Changes

No recorded changes to this operation across all 4 revisions of this API.