---
title: "Update a chart"
method: PATCH
path: "/api/public/organizations/{orgId}/charts/{id}"
tags: ["Charts"]
---

# Update a chart

`PATCH /api/public/organizations/{orgId}/charts/{id}`

## Request

- Base URL: `https://charts.basedash.com`
- URL: `https://charts.basedash.com/api/public/organizations/{orgId}/charts/{id}`
- Auth: HTTP bearer

Updates a chart. Content changes (name, SQL query, chart type, axes, etc.) create a new chart version behind the scenes so the version history is preserved. Placement changes (dashboardId, dashboardTabId, layout) move or resize the chart without creating a version. Requires admin access to the organization.

## Path parameters

- `orgId` string, required: Organization ID
- `id` string, required: Chart ID

## Request body

- UpdateChartInput
  - `dashboardId` string: ID of the dashboard to move the chart to
  - `dashboardTabId` string: ID of the dashboard tab to move the chart to
  - `layout` object: Position and size of the chart on the dashboard grid
    - `x` integer: Column position on the dashboard grid
    - `y` integer: Row position on the dashboard grid
    - `width` integer: Width of the chart in grid units
    - `height` integer: Height of the chart in grid units
  - `name` string: Name of the chart
  - `description` string, nullable: Description of the chart
  - `chartType` union: Type of the chart
    - 'TABLE'
    - 'LINE'
    - 'VERTICAL_BAR'
    - 'HORIZONTAL_BAR'
    - 'SCATTER'
    - 'FUNNEL'
    - 'NUMBER'
    - 'PROGRESS'
    - 'IMAGE'
    - 'RECORD'
    - 'TEXT'
    - 'PIE'
    - 'ACTIVITY'
    - 'MAP'
    - 'SANKEY'
    - 'DASHBOARD_HEADER'
    - 'DASHBOARD_TEXT'
  - `sqlQuery` string: SQL query powering the chart
  - `drilldownSqlQuery` string, nullable: SQL query used for chart drill-downs
  - `databaseConnectionId` string, nullable: ID of the data source the SQL query runs against
  - `xAxisProperty` string, nullable: Result column used for the x-axis
  - `xAxisSecondaryProperty` string, nullable: Result column used to break down the x-axis into segments
  - `yAxisProperty` string, nullable: Result column used for the y-axis
  - `staticContent` string, nullable: Static content for DASHBOARD_HEADER and DASHBOARD_TEXT chart types
  - `numericalFormat` union: How values are formatted. PERCENTAGE expects values on a 0-100 scale (42.5 shows as 42.5%); it does not convert 0-1 ratios.
    - 'NUMBER'
    - 'CURRENCY'
    - 'PERCENTAGE'
  - `currencyCode` string, nullable: ISO 4217 currency code (for example USD or EUR) used when numericalFormat is CURRENCY. Null uses USD.
  - `showFullNumbers` boolean: Show full numbers (1,234,567) instead of abbreviated ones (1.2M).
  - `metricLabel` string, nullable: NUMBER charts: label shown with the value. Null uses the chart name.
  - `timeSeriesMetricType` union: Summary value shown above LINE and VERTICAL_BAR charts: the SUM, AVERAGE or LATEST value of the series, or NONE to hide it. With a breakdown, NONE plus showLegend true shows segment labels only. PIE, FUNNEL and HORIZONTAL_BAR charts show the total unless this is NONE.
    - 'SUM'
    - 'LATEST'
    - 'AVERAGE'
    - 'NONE'
  - `tableMetricType` union: TABLE charts: COUNT shows the record count above the table, NONE hides it.
    - 'NONE'
    - 'COUNT'
  - `showLegend` boolean: Show the series legend (LINE, VERTICAL_BAR, HORIZONTAL_BAR, PIE, FUNNEL and SCATTER charts).
  - `goalLineValue` number, nullable: Value of the target (goal) line on LINE, VERTICAL_BAR and SCATTER charts. Null hides it.
  - `yAxisMinimum` number, nullable: Lower bound of the y-axis. Null picks it from the data.
  - `yAxisMaximum` number, nullable: Upper bound of the y-axis. Null picks it from the data.
  - `xAxisMinimum` number, nullable: SCATTER charts: lower bound of the x-axis. Null picks it from the data.
  - `xAxisMaximum` number, nullable: SCATTER charts: upper bound of the x-axis. Null picks it from the data.
  - `barMode` union: How bars of a VERTICAL_BAR or HORIZONTAL_BAR chart with a breakdown (xAxisSecondaryProperty) combine: STACKED or side by side (GROUPED).
    - 'STACKED'
    - 'GROUPED'
  - `colorByCategory` boolean: Give each bar its own color by category on a single-series HORIZONTAL_BAR, categorical VERTICAL_BAR or FUNNEL chart. segmentColors are then keyed by category (xAxisProperty) value. Ignored while the chart has a breakdown.
  - `seriesColor` 'NEUTRAL' | 'BLUE' | 'ORANGE' | 'PURPLE' | 'RED' | 'TEAL' | 'GREEN' | 'YELLOW' | 'PINK': A color from the chart palette. NEUTRAL is near-black in light mode and near-white in dark mode.
  - `segmentColors` object, nullable: Colors of segments, keyed by segment value: breakdown values on LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL and SCATTER charts, slices on PIE charts, nodes on SANKEY charts, or categories with colorByCategory. Segments left out are colored automatically. Merged by key: null for a segment resets it to automatic; null for the whole field resets every segment.
  - `imageProperty` string, nullable: IMAGE charts: result column holding the image URL.
  - `imageFit` union: IMAGE charts: whether the image covers the card or fits inside it.
    - 'CONTAIN'
    - 'COVER'
  - `imageGrowToFit` boolean: IMAGE charts: grow the image to fill the card.
  - `textProperty` string, nullable: TEXT charts: result column holding the text to show.
  - `mapVariant` union: MAP charts: WORLD (matches country names) or UNITED_STATES (matches state names).
    - 'WORLD'
    - 'UNITED_STATES'
  - `tableColumns` object, nullable: TABLE charts: column widths and pins, keyed by result column name. Columns left out use the defaults. Merged by column: a column given replaces that column's settings, null resets it; null for the whole field resets every column.

## Response `200`

Chart updated successfully

- object
  - `data` ChartResponse, required
    - `id` string, required: Chart ID
    - `createdAt` string, date-time, required: Chart creation timestamp
    - `updatedAt` string, date-time, required: Timestamp of the last content or placement change
    - `dashboardId` string, required: ID of the dashboard the chart is on
    - `dashboardTabId` string, required: ID of the dashboard tab the chart is on
    - `organizationId` string, required: Organization ID
    - `name` string, required: Name of the chart
    - `description` string, nullable, required: Description of the chart
    - `chartType` union, required: Type of the chart
      - 'TABLE'
      - 'LINE'
      - 'VERTICAL_BAR'
      - 'HORIZONTAL_BAR'
      - 'SCATTER'
      - 'FUNNEL'
      - 'NUMBER'
      - 'PROGRESS'
      - 'IMAGE'
      - 'RECORD'
      - 'TEXT'
      - 'PIE'
      - 'ACTIVITY'
      - 'MAP'
      - 'SANKEY'
      - 'DASHBOARD_HEADER'
      - 'DASHBOARD_TEXT'
    - `sqlQuery` string, required: SQL query powering the chart
    - `drilldownSqlQuery` string, nullable, required: SQL query used for chart drill-downs
    - `databaseConnectionId` string, nullable, required: ID of the data source the SQL query runs against
    - `xAxisProperty` string, nullable, required: Result column used for the x-axis
    - `xAxisSecondaryProperty` string, nullable, required: Result column used to break down the x-axis into segments
    - `yAxisProperty` string, nullable, required: Result column used for the y-axis
    - `staticContent` string, nullable, required: Static content for DASHBOARD_HEADER and DASHBOARD_TEXT chart types
    - `numericalFormat` union, required: How values are formatted. PERCENTAGE expects values on a 0-100 scale (42.5 shows as 42.5%); it does not convert 0-1 ratios.
      - 'NUMBER'
      - 'CURRENCY'
      - 'PERCENTAGE'
    - `currencyCode` string, nullable, required: ISO 4217 currency code (for example USD or EUR) used when numericalFormat is CURRENCY. Null uses USD.
    - `showFullNumbers` boolean, required: Show full numbers (1,234,567) instead of abbreviated ones (1.2M).
    - `metricLabel` string, nullable, required: NUMBER charts: label shown with the value. Null uses the chart name.
    - `timeSeriesMetricType` union, required: Summary value shown above LINE and VERTICAL_BAR charts: the SUM, AVERAGE or LATEST value of the series, or NONE to hide it. With a breakdown, NONE plus showLegend true shows segment labels only. PIE, FUNNEL and HORIZONTAL_BAR charts show the total unless this is NONE.
      - 'SUM'
      - 'LATEST'
      - 'AVERAGE'
      - 'NONE'
    - `tableMetricType` union, required: TABLE charts: COUNT shows the record count above the table, NONE hides it.
      - 'NONE'
      - 'COUNT'
    - `showLegend` boolean, required: Show the series legend (LINE, VERTICAL_BAR, HORIZONTAL_BAR, PIE, FUNNEL and SCATTER charts).
    - `goalLineValue` number, nullable, required: Value of the target (goal) line on LINE, VERTICAL_BAR and SCATTER charts. Null hides it.
    - `yAxisMinimum` number, nullable, required: Lower bound of the y-axis. Null picks it from the data.
    - `yAxisMaximum` number, nullable, required: Upper bound of the y-axis. Null picks it from the data.
    - `xAxisMinimum` number, nullable, required: SCATTER charts: lower bound of the x-axis. Null picks it from the data.
    - `xAxisMaximum` number, nullable, required: SCATTER charts: upper bound of the x-axis. Null picks it from the data.
    - `barMode` union, required: How bars of a VERTICAL_BAR or HORIZONTAL_BAR chart with a breakdown (xAxisSecondaryProperty) combine: STACKED or side by side (GROUPED).
      - 'STACKED'
      - 'GROUPED'
    - `colorByCategory` boolean, required: Give each bar its own color by category on a single-series HORIZONTAL_BAR, categorical VERTICAL_BAR or FUNNEL chart. segmentColors are then keyed by category (xAxisProperty) value. Ignored while the chart has a breakdown.
    - `seriesColor` 'NEUTRAL' | 'BLUE' | 'ORANGE' | 'PURPLE' | 'RED' | 'TEAL' | 'GREEN' | 'YELLOW' | 'PINK', required: A color from the chart palette. NEUTRAL is near-black in light mode and near-white in dark mode.
    - `segmentColors` object, required: Colors of segments, keyed by segment value: breakdown values on LINE, VERTICAL_BAR, HORIZONTAL_BAR, FUNNEL and SCATTER charts, slices on PIE charts, nodes on SANKEY charts, or categories with colorByCategory. Segments left out are colored automatically.
    - `imageProperty` string, nullable, required: IMAGE charts: result column holding the image URL.
    - `imageFit` union, required: IMAGE charts: whether the image covers the card or fits inside it.
      - 'CONTAIN'
      - 'COVER'
    - `imageGrowToFit` boolean, required: IMAGE charts: grow the image to fill the card.
    - `textProperty` string, nullable, required: TEXT charts: result column holding the text to show.
    - `mapVariant` union, required: MAP charts: WORLD (matches country names) or UNITED_STATES (matches state names).
      - 'WORLD'
      - 'UNITED_STATES'
    - `tableColumns` object, required: TABLE charts: column widths and pins, keyed by result column name. Columns left out use the defaults.
    - `layout` ChartLayout, required
      - `x` integer, required: Column position on the dashboard grid
      - `y` integer, required: Row position on the dashboard grid
      - `width` integer, required: Width of the chart in grid units
      - `height` integer, required: Height of the chart in grid units
    - `imageUrl` string, uri, required: URL that renders this chart as a PNG image (the "Get a chart image" endpoint). Request it with the same API key authentication.

## Other responses

- `400`: Bad request - Invalid JSON body or validation error
- `401`: Unauthorized - Missing or invalid API key
- `403`: Forbidden - Organization trial has expired
- `404`: Not found - Chart not found or no admin access
- `429`: Rate limit exceeded - Too many requests
- `500`: Internal server error

---

[API](https://skmtc.dev/basedash/apis/basedash-public-api.md) - [All operations](https://skmtc.dev/basedash/apis/basedash-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/basedash/apis/basedash-public-api/revisions/efb9d40bc6f7?raw)