SheetgoDevelopers

Developers › REST API › Workflows & Automations

REST API · 5 endpoints

dashboards

Complete for this group. Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under Models used on this page, so you do not need another page to build a request. Base URL https://dev-api.sheetgo.com; send Authorization: Bearer sg_…. Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards (Markdown).

Conventions for every endpoint. Lists take page (from 1) and per_page (1-100, default 50), and total counts pages, not items. Collection URLs end with /. POST …/run returns 200 when the run is queued; poll GET …/run. Google Sheets use provider: "drive"; column fields take letters ("E"). Error bodies and status codes: api.html#api-errors.

Python recipes. API client helper.

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.

Operations

GET/rest/beta/workflows/{id}/dashboardGet 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.

Parameters
NameInTypeDescription
idpathstringrequiredWorkflow identification
Responses
StatusMeaningBody
200Elements and publish stateDashboardOut
401Authentication failed or token is invalid—
403Not a member of the workflow—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/ID/dashboard" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards#get-rest-beta-workflows-id-dashboard

POST/rest/beta/workflows/{id}/dashboard/elementsAdd 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.

Parameters
NameInTypeDescription
idpathstringrequiredWorkflow identification
Request body (required)

application/json · array of object

Responses
StatusMeaningBody
201The created elementsarray of ElementOut
400Malformed element—
401Authentication failed or token is invalid—
403Requires manager or owner—
404Not found—
409Chart limit reached—
422Source could not be validated—
Example request
curl -s -X POST "https://dev-api.sheetgo.com/rest/beta/workflows/ID/dashboard/elements" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards#post-rest-beta-workflows-id-dashboard-elements

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.

Parameters
NameInTypeDescription
idpathstringrequiredWorkflow identification
element_idpathstringrequiredElement identification
Responses
StatusMeaningBody
204Deleted—
401Authentication failed or token is invalid—
403Requires manager or owner—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X DELETE "https://dev-api.sheetgo.com/rest/beta/workflows/ID/dashboard/elements/ELEMENT_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards#delete-rest-beta-workflows-id-dashboard-elements-element-id

GET/rest/beta/workflows/{id}/dashboard/elements/{element_id}/dataRead 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.

Parameters
NameInTypeDescription
idpathstringrequiredWorkflow identification
element_idpathstringrequiredElement identification
pagequeryintegeroptionalTable elements only
Default: 1 · Min: 1
per_pagequeryintegeroptionalTable elements only
Default: 50 · Min: 1 · Max: 500
Responses
StatusMeaningBody
200The element's current valuesElementDataOut
401Authentication failed or token is invalid—
403Not a member of the workflow—
404Not found—
422Validation ErrorHTTPValidationError
502The values could not be read—
Example request
curl -s -X GET "https://dev-api.sheetgo.com/rest/beta/workflows/ID/dashboard/elements/ELEMENT_ID/data" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"

Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards#get-rest-beta-workflows-id-dashboard-elements-element-id-data

PUT/rest/beta/workflows/{id}/dashboard/publishPublish 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.

Parameters
NameInTypeDescription
idpathstringrequiredWorkflow identification
Request body (required)

application/json · object

Responses
StatusMeaningBody
200Publish statePublishOut
400Malformed or unsupported field—
401Authentication failed or token is invalid—
403Requires manager or owner, or plan upgrade—
404Not found—
422Validation ErrorHTTPValidationError
Example request
curl -s -X PUT "https://dev-api.sheetgo.com/rest/beta/workflows/ID/dashboard/publish" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json

Latest version: https://dev-api.sheetgo.com/rest/reference/dashboards#put-rest-beta-workflows-id-dashboard-publish

Models used on this page

Every request and response model referenced above, including nested ones (8). The full catalogue is on api-models.html.

AuthConfigIn

Access restriction. Only domain restriction is exposed.

specificUsers is deliberately absent: the internal PUT emails every address in it via SendGrid (dashboard/models.py:190), which would let an API key mail arbitrary recipients.

FieldTypeDescription
domainbooleanrequiredRestrict to the workflow owner's email domain

Used by: PUT /rest/beta/workflows/{id}/dashboard/publish

DashboardOut

A workflow's single dashboard: its elements and its publication state.

FieldTypeDescription
elementsarray of ElementOutoptionalEvery element on the dashboard, in stored order. Empty for a workflow whose dashboard has not been built yet.
publishPublishOutrequiredWhether the dashboard is published, and under what access restrictions.

Used by: GET /rest/beta/workflows/{id}/dashboard

ElementDataOut

One element's current values.

page/per_page/total are populated for table only; the other types have nothing to paginate.

FieldTypeDescription
dataanyoptionalThe element's current values, read live from the spreadsheet. A single value for indicator, a list of rows for table, and the chart's image or reference for chart.
idstringrequiredId of the element these values belong to.
pageintegernullableCurrent page of rows, 1-based. Populated for table only.
per_pageintegernullableRows per page in this response. Populated for table only.
totalintegernullableTotal rows, for table elements
typeElementTyperequiredThe element's kind, which determines the shape of data.

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

ElementOut

One stored element, in public vocabulary.

FieldTypeDescription
added_bystringnullableEmail of the user who added the element.
added_onstringnullableWhen the element was added, ISO 8601.
chart_idintegernullableNumeric id of the referenced chart. Set for chart elements only; get it from GET /files/{provider}/{file_id}/structure.
errorstringnullableStored render error, when one was persisted. Usually null even for a broken element: errors are written during a build and not saved (workflow/controller.py:759). Read the element's /data to be sure.
file_idstringnullableId of the Google Sheets file the element reads from.
idstringrequiredElement id. Use it for delete and data reads.
rangestringnullableA1 range the element reads, without the tab name (for example B2:D50). Set for indicator and table; null for chart.
stored_rolestringnullableInternal role, echoed when type is other
stored_typestringnullableInternal type, echoed when type is other
tab_idintegernullableNumeric id of the tab the element reads from. Null for chart elements, which point at a chart rather than a tab.
tab_namestringnullableName of that tab at the time the element was stored. Null for chart elements. Renaming the tab does not update this.
titlestringnullableLabel shown above the element on the dashboard.
typeElementTyperequiredElement kind: indicator (a single value), table (a range of rows) or chart (a reference to a chart already in the spreadsheet). other means an element the web app created that this API does not model — see stored_type.

Used by: POST /rest/beta/workflows/{id}/dashboard/elements

HTTPValidationError

FieldTypeDescription
detailarray of ValidationErroroptional

Used by: GET /rest/beta/workflows/, POST /rest/beta/workflows/, POST /rest/beta/workflows/run/{id}, GET /rest/beta/workflows/{id}, PATCH /rest/beta/workflows/{id}, DELETE /rest/beta/workflows/{id}, GET /rest/beta/workflows/{id}/collaborators, POST /rest/beta/workflows/{id}/collaborators, DELETE /rest/beta/workflows/{id}/collaborators, PATCH /rest/beta/workflows/{id}/collaborators/{email}, DELETE /rest/beta/workflows/{id}/collaborators/{email}, GET /rest/beta/workflows/{id}/destinations, GET /rest/beta/workflows/{id}/files, GET /rest/beta/workflows/{id}/general-access, PUT /rest/beta/workflows/{id}/general-access, DELETE /rest/beta/workflows/{id}/general-access, POST /rest/beta/workflows/{id}/leave, POST /rest/beta/workflows/{id}/request-access, GET /rest/beta/workflows/{id}/run, POST /rest/beta/workflows/{id}/run, GET /rest/beta/workflows/{id}/sources, GET /rest/beta/automations/, POST /rest/beta/automations/run/{id}, GET /rest/beta/automations/{id}, DELETE /rest/beta/automations/{id}, GET /rest/beta/automations/{id}/destinations, GET /rest/beta/automations/{id}/files, GET /rest/beta/automations/{id}/run, POST /rest/beta/automations/{id}/run, GET /rest/beta/automations/{id}/sources, GET /rest/beta/workflows/{id}/trigger, DELETE /rest/beta/workflows/{id}/trigger, GET /rest/beta/workflows/{id}/dashboard, DELETE /rest/beta/workflows/{id}/dashboard/elements/{element_id}, GET /rest/beta/workflows/{id}/dashboard/elements/{element_id}/data, PUT /rest/beta/workflows/{id}/dashboard/publish, GET /rest/beta/workflows/{workflow_id}/forms/, POST /rest/beta/workflows/{workflow_id}/forms/, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}, PATCH /rest/beta/workflows/{workflow_id}/forms/{form_id}, DELETE /rest/beta/workflows/{workflow_id}/forms/{form_id}, GET /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, HEAD /rest/beta/workflows/{workflow_id}/forms/{form_id}/responses, GET /rest/beta/automations/{automation_id}/webhook, GET /rest/beta/workflows/{workflow_id}/webhooks, GET /rest/beta/api-destination/{public_id}, HEAD /rest/beta/api-destination/{public_id}, GET /rest/beta/integrations/{provider}/options, GET /rest/beta/outlook/messages, POST /rest/beta/outlook/messages/batch, GET /rest/beta/outlook/messages/{message_id}, GET /rest/beta/outlook/messages/{message_id}/attachments/{attachment_id}, POST /rest/beta/outlook/send, POST /rest/beta/gmail/send, GET /rest/beta/files/{provider}, GET /rest/beta/files/{provider}/roots, GET /rest/beta/files/{provider}/search, GET /rest/beta/files/{provider}/{file_id}, GET /rest/beta/bigquery/projects, GET /rest/beta/bigquery/projects/{project}/datasets, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables, GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}, POST /rest/beta/bigquery/projects/{project}/validate-query, POST /rest/auth/refresh, POST /rest/auth/token

PublishOut

The dashboard's current publication state.

FieldTypeDescription
auth_configobjectnullableThe access restriction applied when require_auth is true — {"domain": true} limits viewers to the owner's email domain. Null when unrestricted.
public_idstringnullableStable public identifier minted at first publish; it forms the url. Null until the dashboard has been published once.
require_authbooleanoptionalWhether a viewer must be signed in to open the dashboard. Only meaningful while shared is public.
Default: false
sharedstringrequiredpublic if the dashboard is published and reachable at url, private if it is not.
urlstringnullableViewer URL; null while private and never published

Used by: PUT /rest/beta/workflows/{id}/dashboard/publish

ValidationError

FieldTypeDescription
locarray of string or integerrequired
msgstringrequired
typestringrequired