dashboards

Dashboards turn a workflow's data into shareable visual summaries. Each workflow has a single dashboard; add indicator, table and chart-reference elements to it, read an element's live values, and publish the dashboard to get a viewer URL.

Elements point at a spreadsheet's tabs and charts by id — get those from GET /files/{provider}/{file_id}/structure. Google Sheets on Google Drive only.

Base URL: https://dev-api.sheetgo.com. Start page: https://dev-api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: Rate Limiting

Every endpoint is rate limited; see the guide Rate Limiting.

GET /rest/beta/workflows/{id}/dashboard

Get a workflow's dashboard

Elements and publish state in one call. Two Mongo reads, no Sheets access.

elements[].error is usually null even for a broken element: render errors are written during a build and not persisted (workflow/controller.py:759). Read an element's /data to be certain it renders.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Workflow identification

Responses

200 Elements and publish state. Schema: DashboardOut
404 Not found
401 Authentication failed or token is invalid
403 Not a member of the workflow
422 Validation Error. Schema: HTTPValidationError

Read next: DashboardOut, HTTPValidationError.

GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data

Read one dashboard element's current values

Build and return one element's values.

Bounded to a single element: get_workflow_dashboard filters dashboard['data'] down to the requested id, so this is one or two Sheets calls regardless of dashboard size. The element's controlKey is read from storage, never taken from the caller — get_chart_instance matches on it (workflow/dashboard/utils.py:20) and would find nothing without it.

page/per_page apply to table elements only.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Workflow identification
`element_id`	path	string	yes	Element identification
`page`	query	integer	no	Table elements only	default: `1`; min: 1
`per_page`	query	integer	no	Table elements only	default: `50`; min: 1; max: 500

Responses

200 The element's current values. Schema: ElementDataOut
404 Not found
401 Authentication failed or token is invalid
403 Not a member of the workflow
502 The values could not be read
422 Validation Error. Schema: HTTPValidationError

POST /rest/beta/workflows/{id}/dashboard/elements

Add elements to a workflow's dashboard

Create one or more dashboard elements, atomically.

The dashboard itself needs no creating — add_charts brings it into being with the first element (workflow/models.py:1806).

Every element is validated against the real spreadsheet before anything is written, and a single failure rejects the whole batch: a partial write would leave the caller diffing what landed. Validation uses the workflow owner's credentials, since those are what render the dashboard later.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Workflow identification

Request body

Content type application/json. Required.

One or more elements to create.

Body: array of object

Responses

201 The created elements. Schema: array of ElementOut
404 Not found
401 Authentication failed or token is invalid
400 Malformed element
403 Requires manager or owner
409 Chart limit reached
422 Source could not be validated

DELETE /rest/beta/workflows/{id}/dashboard/elements/{element_id}

Delete one dashboard element

Remove one element.

Deleting the LAST element removes the dashboard and takes it offline: remove_chart sets workflow.dashboard = None and marks the publishing record deleted (workflow/models.py:1920, :1932). Adding an element later revives it with the same public_id, so the viewer URL survives.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Workflow identification
`element_id`	path	string	yes	Element identification

Responses

204 Deleted
404 Not found
401 Authentication failed or token is invalid
403 Requires manager or owner
422 Validation Error. Schema: HTTPValidationError

PUT /rest/beta/workflows/{id}/dashboard/publish

Publish or unpublish a workflow's dashboard

Set shared, require_auth and auth_config.domain.

specific_users and visual_schema are rejected. The internal PUT emails every address in authConfig.specificUsers via SendGrid (dashboard/models.py:190); refusing the field is what keeps an API key from mailing arbitrary recipients. Both remain editable in the Sheetgo UI.

Stricter than the internal route, which requires only workflow access (workflow/views.py:936) and so lets a collaborator publish publicly.

Authentication, any one of: default; Developer Access; sheetgo-api-key.

Parameters

Name	In	Type	Required	Description	Allowed values / default / constraints
`id`	path	string	yes	Workflow identification

Request body

Content type application/json. Required.

Publish settings.

Field	Type	Required	Description	Allowed values / default / constraints
`shared`	string	yes	public \| private
`require_auth`	boolean	no	Require a signed-in viewer	default: `false`
`auth_config`	AuthConfigIn, nullable	no

Responses

200 Publish state. Schema: PublishOut
404 Not found
401 Authentication failed or token is invalid
400 Malformed or unsupported field
403 Requires manager or owner, or plan upgrade
422 Validation Error. Schema: HTTPValidationError

More: start page https://dev-api.sheetgo.com/rest/reference.md, everything in one file https://dev-api.sheetgo.com/rest/llms-full.txt, OpenAPI https://dev-api.sheetgo.com/rest/openapi.json.