Skip to main content
GridOS renders charts as overlays anchored to a cell position on a sheet. Each chart reads from a rectangular data range you specify and can be repositioned, resized, or retyped without touching the underlying cell data. The four endpoints below cover the full lifecycle of a chart.

​
GET /system/charts

List all charts on a given sheet. If you omit the sheet query parameter, GridOS returns charts for the currently active sheet.

​
Query Parameters

​
sheet
string
The sheet whose charts you want to retrieve. Defaults to the active sheet when omitted.

​
Response

​
charts
array of objects
All chart objects on the requested sheet. Each object includes the chart’s id, title, chart_type, data_range, anchor_cell, width, height, and orientation.

​
Example

GET /system/charts?sheet=Income%20Statement
Response 
{
  "charts": [
    {
      "id": "chart-a1b2c3",
      "title": "Revenue by Quarter",
      "chart_type": "bar",
      "data_range": "A1:E5",
      "anchor_cell": "G2",
      "width": 400,
      "height": 280,
      "orientation": "columns"
    }
  ]
}

​
POST /system/charts

Create a new chart overlay on a sheet. You must supply a data_range; all other fields have sensible defaults.

​
Request

​
data_range
string
required
The rectangular cell range that contains the chart data, in A1 notation (e.g. "A1:B6"). The range should include both labels and numeric values.
​
anchor_cell
string
The cell where the top-left corner of the chart overlay is pinned. Defaults to "F2". Choose an empty area so the chart does not obscure your data.
​
chart_type
string
The chart type. Accepted values: "bar", "line", "pie". Defaults to "bar".
​
title
string
A display title rendered above the chart. Defaults to an empty string (no title shown).
​
width
integer
Chart width in pixels. Defaults to 400.
​
height
integer
Chart height in pixels. Defaults to 280.
​
orientation
string
Controls how the data range is read. "columns" means the first column contains labels and subsequent columns are series (typical). "rows" means the first row contains labels. Defaults to "columns".
​
sheet
string
The sheet on which to create the chart. Defaults to the active sheet when omitted.

​
Response

​
status
string
"Success" when the chart was created.
​
chart
object
The full chart object including the system-assigned id and all resolved field values.

​
Errors

StatusMeaning
400The chart could not be created (e.g. invalid data range or chart type).

​
Example

POST /system/charts
{
  "anchor_cell": "H2",
  "data_range": "A1:E5",
  "chart_type": "line",
  "title": "Revenue by Quarter",
  "width": 500,
  "height": 320,
  "orientation": "columns",
  "sheet": "Income Statement"
}
Response 
{
  "status": "Success",
  "chart": {
    "id": "chart-a1b2c3",
    "title": "Revenue by Quarter",
    "chart_type": "line",
    "data_range": "A1:E5",
    "anchor_cell": "H2",
    "width": 500,
    "height": 320,
    "orientation": "columns"
  }
}
Chart IDs are assigned by the server at creation time. Store the returned id if you need to update or delete the chart later.

​
PATCH /system/charts/

Update one or more properties of an existing chart. Send only the fields you want to change — all other fields remain as they are.

​
Path Parameters

​
chart_id
string
required
The unique identifier of the chart to update, as returned by POST /system/charts or GET /system/charts.

​
Request

All body fields are optional. Only the fields you include are applied.
​
anchor_cell
string
Move the chart to a new anchor cell.
​
data_range
string
Change the data range the chart reads from.
​
chart_type
string
Change the chart type. Accepted values: "bar", "line", "pie".
​
title
string
Update the chart title.
​
width
integer
New width in pixels.
​
height
integer
New height in pixels.
​
orientation
string
Change between "columns" and "rows" orientation.
​
sheet
string
The sheet on which the chart lives. Required when the chart is not on the active sheet.

​
Response

​
status
string
"Success" when the chart was updated.
​
chart
object
The full updated chart object.

​
Errors

StatusMeaning
404No chart with the given chart_id was found on the specified (or active) sheet.
400The update payload is invalid (e.g. unrecognised chart type).

​
Example

PATCH /system/charts/chart-a1b2c3
{
  "chart_type": "pie",
  "title": "Revenue Share by Quarter",
  "anchor_cell": "J4"
}
Response 
{
  "status": "Success",
  "chart": {
    "id": "chart-a1b2c3",
    "title": "Revenue Share by Quarter",
    "chart_type": "pie",
    "data_range": "A1:E5",
    "anchor_cell": "J4",
    "width": 500,
    "height": 320,
    "orientation": "columns"
  }
}

​
DELETE /system/charts/

Permanently remove a chart overlay from a sheet. The underlying cell data referenced by the chart is not affected.

​
Path Parameters

​
chart_id
string
required
The unique identifier of the chart to delete.

​
Query Parameters

​
sheet
string
The sheet on which to look for the chart. Defaults to the active sheet when omitted.

​
Response

​
status
string
"Success" when the chart was deleted.

​
Errors

StatusMeaning
404No chart with the given chart_id was found on the specified (or active) sheet.

​
Example

DELETE /system/charts/chart-a1b2c3?sheet=Income%20Statement
Response 
{
  "status": "Success"
}
Chart deletion is permanent and cannot be undone via the API. Save your workbook state with POST /system/save before bulk-deleting charts if you want a recovery point.