Skip to main content
POST
Call widget.add

Authorizations

​
Authorization
string
header
required

An API key minted at Settings › API & MCP. Send it as Authorization: Bearer <key>. A key carries its holder's own permissions, resolved on every call — revoking a membership closes the key's reach immediately. Keep it in an environment variable (GOOSY_API_KEY), never in a committed file.

Headers

​
x-request-id
string

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.

Maximum string length: 128
​
Idempotency-Key
string
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.

Maximum string length: 200

Body

application/json
​
kind
enum<string>
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.

Available options:
chart,
table,
kpi,
monitor,
note,
link,
button,
switch,
briefing,
needs_you,
analytics
​
title
string
required

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

Minimum string length: 1
​
board_id
string<uuid>

The desk or project to put it on: a desk id from widget.list (the Dashboard's tabs) or a project id from board.tree. Omit for the Dashboard's first desk.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
metric_keys
enum<string>[]

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

Required array length: 1 - 6 elements
Available options:
rev_leads,
rev_booked_calls,
rev_calls_showed,
rev_show_rate,
rev_sales_won,
rev_revenue_won,
rev_revenue_by_source,
rev_open_pipeline_value,
email_sent,
email_delivered,
email_delivery_rate,
email_opened,
email_open_rate,
email_clicked,
email_click_rate,
email_replied,
email_complaint_rate,
email_bounce_rate,
list_size,
list_new_subscribers,
list_unsubscribe_rate,
ads_spend,
ads_impressions,
ads_clicks,
ads_ctr,
ads_cpc,
ads_cpm,
ads_reach,
ads_frequency,
ads_conversions,
ads_cost_per_lead,
ads_cost_per_booked_call,
ads_attributed_revenue,
vid_views,
vid_watch_time_minutes,
vid_avg_view_duration,
vid_impressions,
vid_impressions_ctr,
vid_subscribers_gained,
vid_net_subscribers,
vid_breakout_score,
soc_posts_published,
soc_impressions,
soc_engagements,
soc_engagement_rate,
soc_meta_impressions,
soc_meta_engagements,
soc_meta_engagement_rate,
soc_fb_impressions,
soc_fb_engagements,
soc_fb_engagement_rate,
soc_ig_impressions,
soc_ig_reach,
soc_ig_engagements,
soc_ig_engagement_rate,
soc_ig_profile_visits,
soc_ig_new_follows,
sys_produced,
hyros_attributed_revenue,
hyros_attributed_leads,
web_sessions,
web_active_users,
web_conversions,
web_revenue,
web_search_impressions,
web_search_clicks,
web_search_ctr,
web_search_position,
site_views,
site_visitors,
site_sessions,
site_conversions,
site_conversion_rate
​
grain
enum<string>

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

Available options:
hour,
day,
week,
month,
quarter,
year,
lifetime
​
window_periods
integer

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

Required range: 1 <= x <= 366
​
compare
enum<string>

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

Available options:
none,
previous_period,
same_period_last_year
​
entity
object

The thing a monitor watches, e.g. {kind: 'ad_set', id: '...'}. Required for that kind.

​
condition
object

The 'tell me when' threshold. 'no_change_for' takes a number of days as its value.

​
link_target_kind
enum<string>

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

Available options:
page,
site,
board,
data_table
​
link_target_id
string

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.

Minimum string length: 1
​
note_body
string

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

Required string length: 1 - 8000
​
site_id
string<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.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
page_path
string

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.

Required string length: 1 - 1024
​
label
string

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

Required string length: 1 - 200
​
press_tool
string

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.

Pattern: ^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$
​
press_automation_id
string<uuid>

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

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
switch_automation_id
string<uuid>

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

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
switch_data_table_id
string<uuid>

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

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
switch_row_id
string<uuid>

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

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$
​
switch_column
string

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

Pattern: ^[a-z][a-z0-9_]{0,63}$
​
expires_in_days
integer

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

Required range: 1 <= x <= 366
​
idempotency_key
string

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

Required string length: 1 - 200
​
workspace
string

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.

Minimum string length: 1

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.

The tool ran and answered.

​
ok
boolean
required
​
widget_id
string
required
​
board_id
string | null
required
​
answer_note
string
required
​
replayed
boolean
required

True when this is the first result of an earlier call with the same idempotency_key, returned without writing anything again.

​
workspace
string
required

The slug of the workspace this call ran in.

​
working_in
object
required

Which workspace this call ran in, and how that was decided. Present on every workspace-scoped result.