# Update Analytics Page

Rename a page, change its icon, display, theme or style, pause or resume it, or file it in a folder. Only the fields you send change. Editors can change the name, description and display; the rest is the owner's.

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

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

- `name` (string): The page title.
- `description` (string): The line under the title.
- `icon` (string): An icon id.
  An icon id from the app icon catalog, such as chart-bar. An unknown id is refused with the closest ids.
- `iconColor` (string): An icon color from the palette.
  An icon colour from the app palette. An unknown value is refused with the palette.
- `fullWidth` (boolean): Span the whole window.
  Whether the page spans the whole window.
- `showPanelSources` (boolean): Show each panel's source app icons.
  Whether each panel shows its data sources' app icons.
- `themeId` (string): A theme id, from List Analytics Themes, or null.
  A theme id from List Analytics Themes, or null to follow the folder or company default.
- `style` (object): Style overrides by option key.
  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): Pause or resume refreshing.
  true stops the page's data from refreshing; false resumes it (a folder above it can still keep it paused).
- `folderId` (string): A folder id, from List Analytics Folders, or null.
  One of the creator's folders to file the page in, from List Analytics Folders, or null for the top of the sidebar. Filing is the creator's own and changes nothing for anyone else.

## Example request

```bash
curl --request PUT \
  --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Pipeline health",
  "description": "Open deals by stage and owner",
  "icon": "chart-bar",
  "iconColor": "#60a5fa",
  "fullWidth": true,
  "themeId": "Th6Np2Vx8LcQ",
  "style": {
    "cardRadius": "large"
  },
  "folderId": "Fd4Kq8Wm2PzR"
}'
```

## Response fields

- `id` (string): The page id.
- `name` (string): The page title.
- `description` (string): The line under the title, or null.
- `type` (string): What kind of page it is.
  Allowed values:
    - `page`: An ordinary page in the sidebar.
    - `report`: A report: one written panel that fills the page.
    - `subpage`: A page opened from a click on another page, not listed on its own.
- `access` (string): What the key's creator can do on it.
  Allowed values:
    - `owner`: The key's creator owns the page.
    - `edit`: Shared with the creator to edit.
    - `view`: Shared with the creator to view.
- `ownerId` (string): The owner's userId, from List Members.
- `ownerName` (string): The owner's name.
- `folderId` (string): The creator's folder the page is filed in (from List Analytics Folders), or null when it is unfiled or shared with them.
- `icon` (string): The page icon id, or null.
- `iconColor` (string): The page icon color, or null.
- `isPaused` (boolean): Whether its data stopped refreshing, by the page itself or a folder above it.
- `pausedByFolderId` (string): The folder that paused it (from List Analytics Folders), or null.
- `hasShares` (boolean): Whether anyone besides the owner can open it.
- `linkedFromPageIds` (array of string): The pages whose clicks open this one, from List Analytics Pages.
- `createdOn` (date): When it was created.
- `updatedOn` (date): When the page or one of its panels last changed.
- `fullWidth` (boolean): Whether the page spans the whole window.
- `showPanelSources` (boolean): Whether each panel shows its data sources' app icons.
- `themeId` (string): The theme the page wears, from List Analytics Themes, or null to follow its folder or the company default.
- `style` (object): Style overrides on top of the theme, by option, or null.
- `variables` (array of objects): The page variables (its filters), in page order, in the shape Set Analytics Page Variables takes.
  - `name` (string): The variable name. Queries read it as $<name>.
  - `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 empty when the page has none.
  - `id` (string): The tab id.
  - `name` (string): The tab name.
- `version` (object): Which version this answer shows and where the page stands.
  - `mode` (string): draft when it shows the draft, published when it shows the version viewers see.
    Allowed values:
      - `draft`
      - `published`
  - `publishedVersion` (number): The number of the version viewers see, or null when never published.
  - `publishedVersionId` (string): Its id, from List Analytics Page Versions, or null.
  - `publishedOn` (date): When it was published, or null.
  - `hasUnpublishedChanges` (boolean): Editors only: whether the draft differs from the published version. Null for viewers and never-published pages.
- `panels` (array of objects): The panels in this version, with where each sits, as Get Analytics Panel answers them (which answers one in full).
  - `id` (string): The panel id.
  - `name` (string): The panel's title, shown in its card header.
  - `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.
  - `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.
- `revision` (string): The draft revision, when this answer shows the draft to an editor: send it in If-Match with the next change to the page. Null otherwise.