# 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](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://dev-api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="get-rest-beta-workflows-id-dashboard"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/DashboardOut.md)
- `404` Not found
- `401` Authentication failed or token is invalid
- `403` Not a member of the workflow
- `422` Validation Error. Schema: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [DashboardOut](https://dev-api.sheetgo.com/rest/reference/models/DashboardOut.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-workflows-id-dashboard-elements-element-id-data"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/ElementDataOut.md)
- `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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [ElementDataOut](https://dev-api.sheetgo.com/rest/reference/models/ElementDataOut.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="post-rest-beta-workflows-id-dashboard-elements"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/ElementOut.md)
- `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

Read next: [ElementOut](https://dev-api.sheetgo.com/rest/reference/models/ElementOut.md), [ElementType](https://dev-api.sheetgo.com/rest/reference/models/ElementType.md).

<a id="delete-rest-beta-workflows-id-dashboard-elements-element-id"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="put-rest-beta-workflows-id-dashboard-publish"></a>
## 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](https://dev-api.sheetgo.com/rest/reference/models/AuthConfigIn.md), nullable | no |  |  |

**Responses**

- `200` Publish state. Schema: [PublishOut](https://dev-api.sheetgo.com/rest/reference/models/PublishOut.md)
- `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](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [AuthConfigIn](https://dev-api.sheetgo.com/rest/reference/models/AuthConfigIn.md), [HTTPValidationError](https://dev-api.sheetgo.com/rest/reference/models/HTTPValidationError.md), [PublishOut](https://dev-api.sheetgo.com/rest/reference/models/PublishOut.md).

---

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.