# Set Analytics Page Definition Set a page's whole draft in one call: the fastest way to build a page, and the one to use from an agent. Send the page settings, variables, tabs and panels as Get Analytics Page Definition answers them. Name a panel or tab the page has by its id; give a new one a ref of your own and name it by that ref anywhere in the body: a click's panelId, a container's items, a panel's tabId. A panel left out is deleted; settings, variables and tabs left out stay as they are. Within a panel only what differs from the draft is written: a field you send replaces it, except the maps format, links and style and each settings block, which merge over what is stored; send a key as null to remove it. A tab left out is deleted, and a panel you keep must name a tab you keep in tabId; tabs null turns tabs off and keeps every panel. Data sources are not part of a page: make them with Create Analytics Data Source first and name them in each panel's dataSources. Every problem is answered at once, each with its JSON Pointer, before anything is written. The whole change is one undo step (Undo Analytics Page reverses it). Send the revision you last read in If-Match. The answer is the definition as written, with the id each ref got. Viewers see the change once the page is published. `PUT https://connect.mindcloud.co/v2/analytics/pages/:pageId/definition` Permissions: `analytics:page:edit`. ## Parameters ### Path - `pageId` (string, required): The page id, from List Analytics Pages. ### Headers - `If-Match` (string, required): Required. The revision you last read: the `revision` from its read (Get Workflow Definition for a workflow, Get Analytics Page Definition for an Analytics page, Get Analytics Data Source Table for a fixed source's table), or `meta.revision` from your last change to it. The `ETag` header of either answer is the same value, ready to send back. The change applies only if nobody changed it since: otherwise it answers 412 with the current revision in `error.details.revision`. Send it as a strong entity tag (`"r_..."`): a weak one (`W/"..."`) never matches and answers 412. Without it the request answers 428. - `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations). ### Body - `page` (object): The page settings; only those that differ are written. The page settings, as Update Analytics Page takes them. Left out, they stay as they are; a setting left out of page stays too. - `name` (string): The page title. - `description` (string): The line under the title, or null when it has none. - `icon` (string): An icon id from the app icon catalog, or null when it has none. - `iconColor` (string): An icon color from the app palette, or null when it has none. - `fullWidth` (boolean): Whether the page spans the whole window. - `showPanelSources` (boolean): Whether each panel shows its data sources' app icons. - `themeId` (string): A theme id from List Analytics Themes, or null to follow the folder or company default. - `style` (object): Style overrides on top of the theme, by option key, such as { "seriesColors": [...] }. Each option sent replaces that option, null clears one, and style null clears every override. Values are checked against the theme's option registry. - `isPaused` (boolean): true stops the page's data from refreshing; false resumes it (a folder above it can still keep it paused). - `variables` (array): Every page variable, in page order. Every variable (filter) the page should have, in page order, as Set Analytics Page Variables takes them. Left out, they stay as they are. - `tabs` (array): Every tab, in order, or null for none. Every tab the page should have, in order, or null for no tabs. Left out, they stay as they are. A tab left out is deleted with the panels on it. - `id` (string): An existing tab id, from Get Analytics Page Definition, to keep that tab. - `ref` (string): Your own name for a new item, used in place of its id anywhere in this body. The answer maps each ref to the id it got. - `name` (string, required): The tab name. - `panels` (array, required): Every panel the page should have. A new one has a ref; an existing one its id. Every panel the page should have, at most 100. A panel left out is deleted. - `id` (string): An existing panel id on this page, from Get Analytics Page Definition, to keep and change that panel. - `ref` (string): Your own name for a new item, used in place of its id anywhere in this body. The answer maps each ref to the id it got. - `name` (string): The panel's title. Setting it turns off automatic renaming for this panel. - `description` (string): The line under the title when the panel opens as a full-page drill-down view. An empty string clears it. - `placement` (string): page puts the panel on the grid; drill takes it off the grid, to open when another panel drills into it. Allowed values: - `page` - `drill` - `dataSources` (array of objects): Every data source feeding the panel, in order. Replaces the list. - `dataSourceId` (string, required): The data source, from List Analytics Data Sources. - `alias` (string): The name the query and transform code use for the source's rows. Made from the source's name when left out. - `query` (string): DuckDB SQL over the source's rows, with the alias as the table name: filter, group, sort and limit here. An empty string shows every row. - `followPageDate` (boolean): false keeps the page's date filter off this source (an all-time figure). - `transformCode` (string): JavaScript function body receiving each source as a named input ({ alias }) and returning the rows to show. Use it only for what SQL cannot do. Saving it runs it; read the result with Get Analytics Panel Output. An empty string removes it. - `displayType` (string): How the panel draws its rows. One of: table, bar, line, combo, pareto, bump, scatter, bubble, quadrant, pie, treemap, heatmap, pivot, cohort, statusgrid, activity, funnel, waterfall, sankey, chord, statetimeline, timeline, stat, trend, progress, gauge, bullet, report, document, workbook, html, map, region, tabs, group. Allowed values: - `table` - `bar` - `line` - `combo` - `pareto` - `bump` - `scatter` - `bubble` - `quadrant` - `pie` - `treemap` - `heatmap` - `pivot` - `cohort` - `statusgrid` - `activity` - `funnel` - `waterfall` - `sankey` - `chord` - `statetimeline` - `timeline` - `stat` - `trend` - `progress` - `gauge` - `bullet` - `report` - `document` - `workbook` - `html` - `map` - `region` - `tabs` - `group` - `columns` (array of objects): Table panels: the columns shown, in order. Replaces the list; an empty list lets the panel pick its columns from the rows. Null clears them. - `key` (string, required): The row key to show (dot paths allowed). A button column takes an identifier you choose, which names its click event "button:". - `type` (string): How the value is formatted: string, number, percent, ratio, currency, duration, rank, boolean, date, object, list, html, button. Allowed values: - `string` - `number` - `percent` - `ratio` - `currency` - `duration` - `rank` - `boolean` - `date` - `object` - `list` - `html` - `button` - `label` (string): Button columns: the text on the button. - `tooltip` (string): Button columns: one sentence shown on hover. - `width` (number or string): The width in pixels, 64-800. An empty string returns it to the width of its content. - `format` (object): How each column's values are formatted, keyed by column: { "": { "type": "currency" } }. Merged over what is stored; null for a column takes its format off. Null clears every format. - `links` (object): Table panels: the link each cell of a column opens, keyed by column. Merged over what is stored; null for a column takes its link off. Null clears every link. - `style` (object): The color of each series or category, keyed by its name. Merged over what is stored; null for a name takes its color off. Null clears every color. - `settings` (object): The settings of the panel's display type, keyed by block (annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group), as Get Analytics Panel answers them. A block is refused on a type that does not draw it. - `annotations` (object): The annotations settings. A block you send is merged over the stored one: send only the fields you change. - `tooltip` (object): The tooltip settings. A block you send is merged over the stored one: send only the fields you change. - `chart` (object): The chart settings. A block you send is merged over the stored one: send only the fields you change. - `bump` (object): The bump settings. A block you send is merged over the stored one: send only the fields you change. - `scatter` (object): The scatter settings. A block you send is merged over the stored one: send only the fields you change. - `pie` (object): The pie settings. A block you send is merged over the stored one: send only the fields you change. - `treemap` (object): The treemap settings. A block you send is merged over the stored one: send only the fields you change. - `cellGrid` (object): The cellGrid settings. A block you send is merged over the stored one: send only the fields you change. - `statusGrid` (object): The statusGrid settings. A block you send is merged over the stored one: send only the fields you change. - `activity` (object): The activity settings. A block you send is merged over the stored one: send only the fields you change. - `funnel` (object): The funnel settings. A block you send is merged over the stored one: send only the fields you change. - `waterfall` (object): The waterfall settings. A block you send is merged over the stored one: send only the fields you change. - `sankey` (object): The sankey settings. A block you send is merged over the stored one: send only the fields you change. - `chord` (object): The chord settings. A block you send is merged over the stored one: send only the fields you change. - `statetimeline` (object): The statetimeline settings. A block you send is merged over the stored one: send only the fields you change. - `stat` (object): The stat settings. A block you send is merged over the stored one: send only the fields you change. - `trend` (object): The trend settings. A block you send is merged over the stored one: send only the fields you change. - `target` (object): The target settings. A block you send is merged over the stored one: send only the fields you change. - `report` (object): The report settings. A block you send is merged over the stored one: send only the fields you change. - `document` (object): The document settings. A block you send is merged over the stored one: send only the fields you change. - `workbook` (object): The workbook settings. A block you send is merged over the stored one: send only the fields you change. - `html` (object): The html settings. A block you send is merged over the stored one: send only the fields you change. - `map` (object): The map settings. A block you send is merged over the stored one: send only the fields you change. - `region` (object): The region settings. A block you send is merged over the stored one: send only the fields you change. - `tabs` (object): The tabs settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid. - `group` (object): The group settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid. - `on` (object): What clicking the panel's items does, keyed by event: rowClick, valueClick and the other events the display type fires, or "button:" for a button column. Replaces every wiring; null clears them all. - `interaction` (object): Stat panels: make the tile a control that flips a toggle page variable. null makes it a normal panel again. - `toggles` (string, required): The toggle page variable the tile flips. - `params` (object): Drill-down panels: labels for the $params the source SQL reads, keyed by param. Replaces them; null clears them. - `displayCode` (string): Advanced display: JavaScript function body that returns the display settings from the page variables. It is run when you save. An empty string goes back to the static settings and keeps the code. - `aiSnippetsCode` (string): Report panels: JavaScript function body returning { KEY: { prompt, additionalContext } } for the {{KEY}} tokens the transform writes. An empty string removes it. - `layout` (object): The panel's place on the grid. Null on a drill-down or a panel inside a container, which take none; null on a grid panel keeps its place. - `x` (number, required): Leftmost column, 0-11. - `y` (number, required): Top row, from 0. - `w` (number, required): Width in columns, 1-12. - `h` (number): Height in rows; null or left out keeps the panel as tall as what it shows. - `heightMode` (string): auto takes a fixed height off, so the panel is as tall as what it shows. Allowed values: - `auto` - `tabId` (string): The tab the panel sits on: a tab id, or a tab ref from tabs. Required on a new grid panel when the page has tabs; null keeps an existing panel on its tab. - `confirmationReceipts` (array): Every receipt a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED answered for this body. Only after a 409 ANALYTICS_EMBED_CONFIRMATION_REQUIRED for this body: every confirmationReceipt such answers gave, confirming the changes to the published embeds they list. A body that deletes several embedded panels or tabs collects one receipt per deletion. - `revision` (string): Ignored; send the revision in If-Match. Ignored, so a definition read can be sent back as it is. Send the revision in If-Match. ## Example request ```bash curl --request PUT \ --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA/definition' \ --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "page": { "name": "Orders overview", "fullWidth": true }, "variables": [ { "name": "date", "type": "dateRange", "default": "last30d" } ], "panels": [ { "ref": "byMonth", "name": "Orders by month", "displayType": "bar", "dataSources": [ { "dataSourceId": "Ds3Hq9Lp2WxM", "query": "SELECT date_trunc('\''month'\'', created_on) AS month, count(*) AS orders FROM orders GROUP BY 1 ORDER BY 1" } ], "settings": { "chart": { "xKey": "month", "series": [ { "key": "orders" } ] } }, "layout": { "x": 0, "y": 0, "w": 12 }, "on": { "valueClick": { "action": "drillDown", "panelId": "monthOrders" } } }, { "ref": "monthOrders", "name": "Orders that month", "placement": "drill", "displayType": "table", "dataSources": [ { "dataSourceId": "Ds3Hq9Lp2WxM", "query": "SELECT * FROM orders WHERE date_trunc('\''month'\'', created_on) = $month" } ] } ], "confirmationReceipts": [ "eyJmaW5nZXJwcmludCI6IjhkNGMifQ" ], "revision": "r_8a01ddd954aa23f1cc6776b32a2acccd" }' ``` ## Response fields - `page` (object): The page settings, as Update Analytics Page takes them. - `name` (string): The page title. - `description` (string): The line under the title, or null. - `icon` (string): The page icon id, or null. - `iconColor` (string): The page icon color, or null. - `fullWidth` (boolean): Whether the page spans the whole window. - `showPanelSources` (boolean): Whether each panel shows its data sources' app icons. - `themeId` (string): The page theme, from List Analytics Themes, or null when it follows its folder or the company default. - `style` (object): Style overrides on top of the theme, by option key, or null. - `isPaused` (boolean): Whether the page's own data refreshes are paused. - `variables` (array of objects): The page variables (its filters), in page order, as Set Analytics Page Variables takes them. - `name` (string): The variable name. Queries read it as $. - `type` (string): What it holds. Allowed values: - `dateRange`: A date window. - `select`: One value, or several with multiple, from a list of choices. - `search`: Free text a viewer types. - `toggle`: An on or off switch. - `control` (string): chip shows a picker on the page; none has no picker. Allowed values: - `chip` - `none` - `label` (string): The picker label. - `default` (object): What the page opens with: a date preset or range, all or a choice value, or true or false for a toggle. - `multiple` (boolean): A select that takes several choices. - `labeledBy` (string): A select set by a row click: the clicked row field that names the value. - `options` (object): A select: where its choices come from, as dataSourceId with query or valueField and labelField, or typed values. - `presets` (array): A dateRange: its preset menu, in order. - `showCalendar` (boolean): A dateRange: false allows presets only. - `timeGranularity` (boolean): A dateRange: custom ranges carry times. - `tabs` (array of objects): The page tabs, in order, or null when the page has none. - `id` (string): The tab id. - `name` (string): The tab name. - `panels` (array of objects): Every panel in the draft, in the shape Update Analytics Panel takes, with its grid place and tab. - `id` (string): The panel id. - `name` (string): The panel's title, shown in its card header. - `description` (string): The line under the title when the panel opens as a full-page drill-down view. - `placement` (string): Where the panel shows. Allowed values: - `page`: On the page grid. - `drill`: Off the grid: it opens when a click on another panel drills into it, narrowed by the clicked row. - `displayType` (string): How the panel draws its rows. One of: table, bar, line, combo, pareto, bump, scatter, bubble, quadrant, pie, treemap, heatmap, pivot, cohort, statusgrid, activity, funnel, waterfall, sankey, chord, statetimeline, timeline, stat, trend, progress, gauge, bullet, report, document, workbook, html, map, region, tabs, group. Allowed values: - `table`: Draws a table panel. - `bar`: Draws a bar panel. - `line`: Draws a line panel. - `combo`: Draws a combo panel. - `pareto`: Draws a pareto panel. - `bump`: Draws a bump panel. - `scatter`: Draws a scatter panel. - `bubble`: Draws a bubble panel. - `quadrant`: Draws a quadrant panel. - `pie`: Draws a pie panel. - `treemap`: Draws a treemap panel. - `heatmap`: Draws a heatmap panel. - `pivot`: Draws a pivot panel. - `cohort`: Draws a cohort panel. - `statusgrid`: Draws a statusgrid panel. - `activity`: Draws a activity panel. - `funnel`: Draws a funnel panel. - `waterfall`: Draws a waterfall panel. - `sankey`: Draws a sankey panel. - `chord`: Draws a chord panel. - `statetimeline`: Draws a statetimeline panel. - `timeline`: Draws a timeline panel. - `stat`: Draws a stat panel. - `trend`: Draws a trend panel. - `progress`: Draws a progress panel. - `gauge`: Draws a gauge panel. - `bullet`: Draws a bullet panel. - `report`: Draws a report panel. - `document`: Draws a document panel. - `workbook`: Draws a workbook panel. - `html`: Draws a html panel. - `map`: Draws a map panel. - `region`: Draws a region panel. - `tabs`: Draws a tabs panel. - `group`: Draws a group panel. - `dataSources` (array): The data sources feeding the panel, in order. - `dataSourceId` (string): The data source, from List Analytics Data Sources. - `alias` (string): The name the source's query and the transform code use for its rows. - `query` (string): DuckDB SQL over this source's rows, with the alias as the table name. Empty when the panel shows every row as stored. - `followPageDate` (boolean): Whether the page's date filter narrows this source. False for an all-time figure on a date-filtered page. - `transformCode` (string): JavaScript function body that receives each source as a named input and returns the rows to show. Empty when the source queries return the rows directly. - `columns` (array): Table panels: the columns shown, in order. Null when the panel picks its columns from the rows. - `key` (string): The row key the column shows (dot paths allowed). For a button column, the identifier that names its click event. - `type` (string): How the value is formatted and aligned. Absent for plain text. Allowed values: - `string`: Formats the value as string. - `number`: Formats the value as number. - `percent`: Formats the value as percent. - `ratio`: Formats the value as ratio. - `currency`: Formats the value as currency. - `duration`: Formats the value as duration. - `rank`: Formats the value as rank. - `boolean`: Formats the value as boolean. - `date`: Formats the value as date. - `object`: Formats the value as object. - `list`: Formats the value as list. - `html`: Formats the value as html. - `button`: Formats the value as button. - `label` (string): Button columns: the text on the button. - `tooltip` (string): Button columns: the sentence shown on hover. - `width` (number): The column width in pixels for everyone. Absent when the column is as wide as its content. - `format` (object): How each column's values are formatted, keyed by column, for any display type: { "": { "type": "currency", ... } }. Null when none is set. - `links` (object): Table panels: the link each cell of a column opens, keyed by column. Null when none is set. - `style` (object): The color of each series or category, keyed by its name. Null when none is set. - `settings` (object): The settings of the panel's display type, keyed by block: annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group. Only the blocks the panel stores are present. - `on` (object): What clicking the panel's items does, keyed by event (rowClick, valueClick, "button:" ...): { "rowClick": { "action": "navigatePage", "pageId": "..." } }. Empty when nothing is wired. - `interaction` (object): Stat panels: the toggle page variable a click on the tile flips. Null for a normal panel. - `toggles` (string): The toggle page variable. - `params` (object): Drill-down panels: the human label of each $param its SQL reads, keyed by param: { "userId": { "label": "User", "labeledBy": "userName" } }. Null when none is declared. - `displayCode` (string): JavaScript function body that returns the display settings from the page variables. Kept, but unused, while displayMode is basic. - `aiSnippetsCode` (string): Report panels: JavaScript function body returning the AI-written sections of the report. Empty when it has none. - `layout` (object): The panel's place on the page grid. Null when it was never placed (it then flows full width in creation order), and for a drill-down or a panel inside a container. - `x` (number): Leftmost column on the 12-column grid, 0-11. - `y` (number): Top row, from 0. - `w` (number): Width in columns, 1-12. - `h` (number): Height in rows (one row is about 48px). Null when the panel is as tall as what it shows. - `tabId` (string): The page tab the panel sits on, from Get Analytics Page. Null on a page without tabs, and for a drill-down or a panel inside a container. - `revision` (string): The draft revision: send it in If-Match to Set Analytics Page Definition. It changes whenever anything in this definition does. - `refs` (object): The id each new panel and tab got, by its ref. - `panels` (object): { : } for each new panel. - `tabs` (object): { : } for each new tab.