# Validate Analytics Page Definition Check a body for Set Analytics Page Definition without saving anything. It answers every problem Set would refuse, each with its JSON Pointer. Unlike Validate Workflow Definition it answers no definition or refs: a new panel gets its id only when it is written, so Set Analytics Page Definition answers both. A click or container naming a panel the body creates is checked for its event and target here, and in full when it is written. `POST https://connect.mindcloud.co/v2/analytics/pages/:pageId/definition/validate` Permissions: `analytics:page:edit`. ## Parameters ### Path - `pageId` (string, required): The page id, from List Analytics Pages. ### Headers - `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 POST \ --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA/definition/validate' \ --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 - `valid` (boolean): True when Set Analytics Page Definition would accept this body against the draft as it is now. - `revision` (string): The draft revision it was checked against. - `issues` (array of objects): Every problem with the body, each with its JSON Pointer. - `path` (string): A JSON Pointer to the problem in the body. - `code` (string): What is wrong, such as UNKNOWN_PANEL, DUPLICATE_REF or INVALID_ARGS. - `message` (string): What is wrong and how to fix it.