# Create Analytics Panel

Add a blank panel to a page you own, or copy one with fromPanelId. Then set its sources and display with Update Analytics Panel.

`POST https://connect.mindcloud.co/v2/analytics/pages/:pageId/panels`

Permissions: `analytics:page:edit`.

## Parameters

### Path

- `pageId` (string, required): The page to add the panel to, 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

- `name` (string): What the panel is called.
  What the panel is called. Kept as sent: it is never renamed automatically. Left out, it is named after what it shows once it has data.
- `placement` (string): page or drill.
  page (the default) puts it on the grid; drill makes a drill-down target that opens when another panel is clicked.
  Allowed values:
    - `page`
    - `drill`
- `layout` (object): Where it goes on the grid.
  Where it goes on the 12-column grid. Left out, it goes below the other panels.
  - `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. Leave it out to size the panel to what it shows.
- `tabId` (string): The page tab it goes on, from Get Analytics Page.
  The page tab it goes on, from Get Analytics Page. Required when the page has tabs.
- `fromPanelId` (string): A panel to copy, from Get Analytics Page.
  Copy this panel, with its sources and settings, instead of adding a blank one. From Get Analytics Page.
- `fromPageId` (string): The page of the panel to copy, from List Analytics Pages.
  The page fromPanelId is on, when it is not this page. It must be one the key's creator owns.
- `acknowledgeWarnings` (boolean): Copy anyway when the copy loses something.
  Copy anyway when the copy loses page variables or click wiring at this page. Without it, such a copy answers 409 with details.warnings.

## Example request

```bash
curl --request POST \
  --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA/panels' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Orders by month",
  "placement": "page",
  "layout": {
    "x": 0,
    "y": 0,
    "w": 6
  },
  "tabId": "Tb3Kx9Lm2QwE",
  "fromPanelId": "Kd4Rw8Zn1VbQ",
  "fromPageId": "Pq7Lm2Xc9RtA"
}'
```

## Response fields

- `id` (string): The panel id.
- `pageId` (string): The page the panel is on, from List Analytics Pages.
- `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 of objects): 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 of objects): 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: { "<column>": { "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:<column key>" ...): { "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.
- `displayMode` (string): Whether the display comes from the settings or from displayCode.
  Allowed values:
    - `basic`: The display settings above.
    - `advanced`: displayCode returns the display settings from the page variables.
- `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.
- `containedBy` (string): The container panel (tabs or group) it renders inside, or null when it sits on the grid or is a drill-down.
- `createdOn` (date): When the panel was created. Null on a published version of the page.
- `updatedOn` (date): When the panel last changed. Null on a published version of the page.