Manage workbooks as code (Beta)

You can use the Sigma API to retrieve, update, and create workbooks based on a JSON or YAML representation. These endpoints enable a programmatic workflow, allowing you to manage and review workbooks without using the Sigma UI.

Use these endpoints when you want to:

• Develop workbooks using AI assistants
• Automate and scale the creation and management of dashboards
• Integrate workbook development with external tools

About representing workbooks as code

Sigma offers programmatic workbook API endpoints, which use a JSON or YAML representation of a workbook as the input and output. The representation, sometimes referred to as a schema or specification, defines the structure of the workbook, including its data sources, pages, and elements. Additionally, you can specify the configuration of elements and their layout on the workbook canvas.

Using these endpoints, you can programmatically create and manage dashboards using tables, pivot tables, and chart elements. To see supported and unsupported workbook features, see Limitations.

The representation does not include data from your data sources. It lists IDs, which reference the data sources, and then describes how to arrange the contents of the data sources in the workbook. For example, instead of listing individual records like a CSV file, the representation lists the columns of a table and the connection those columns are sourced from.

As Sigma releases new versions of this specification to add fields, change data types, and more, the schemaVersion field in the representation is incremented for new representations. The schemaVersion field is required when creating or updating a workbook to ensure backwards compatibility.

User requirements

The ability to create and manage workbooks from code requires the following:

• You must be the workbook owner or be granted Can edit access to the workbook.
• You must have developer credentials for the Sigma API. For more information, see Get started with the Sigma REST API.
• The user associated with your API credentials must be assigned an account type with the Create, edit, and publish workbooks permission enabled.

Limitations

The following element types are supported in the workbook code representation:

• All table elements
• Pivot tables
• All control elements
• The following chart types: Bar, line, donut, pie, KPI, combo, scatter, area, point map, region map, geography map
• The following layout elements: Container
• The following UI elements: Text, image, divider, embed

📘

To see the configurations and required fields for each supported element type, visit the corresponding page in the Workbook representation example library.

All other element types and features are not supported, including but not limited to the following:

• Python element
• All input table elements
• The following chart elements: Box plot, waterfall, Sankey, funnel, and gauge
• The following UI elements: Button, plugin, page break, value list
• The following layout elements: Repeated container, tabbed container, modal, popover, navigation, form, single row container
• Action sequences
• Workbook and page-level settings such as background color, themes, fonts, custom page panels, and more
• Many configurations of supported elements, such as trellis charts

To review all element types, properties, and values supported in the representation, see the /workbookspec endpoints in the Sigma OpenAPI Definition.

Get the code representation of an existing workbook

To retrieve the code representation of an existing workbook, call the Get the code representation of a workbook endpoint with the workbookId for the workbook:

1. Identify the existing workbook you want the representation for by name, owner, or other details.
2. Call the List workbooks endpoint to retrieve the workbookId for the workbook.
3. Call the Get the code representation of a workbook endpoint, passing the workbookId as a path parameter.

The endpoint returns the code representation of the workbook.

For step-by-step instructions, see Get the code representation of a workbook (Beta).

Create a workbook from a code representation

To create a workbook from a code representation, call the Create a workbook from a code representation endpoint with the code representation in the request body.

1. Prepare a code representation of the workbook you want to create. This might be based on a representation retrieved from an existing workbook, or it might be a new representation. For example representations, see the Example library.
2. Call the Create a workbook from a code representation endpoint, passing the code representation in the request body.

The endpoint creates the workbook and returns the workbookId in the response body.

For step-by-step instructions, see Create a workbook from a code representation.

Update an existing workbook from a code representation

To update an existing workbook from a code representation, call the Update a workbook from a representation endpoint with the code representation in the request body.

1. Identify the existing workbook you want to update, by name, owner, or other details.
2. Call the List workbooks endpoint to retrieve the workbookId for the workbook.
3. Prepare a code representation of the workbook with the updates you want to apply. For an example, see the Example library.
4. Call the Update a workbook from a representation endpoint, passing the workbookId as a path parameter and the code representation in the request body.

The endpoint updates the workbook.

For step-by-step instructions, see Update a workbook from a code representation.

🚩

The Update a workbook from a representation endpoint does not support partial updates. To update a workbook, you must provide a complete representation of the workbook, even if you are only making minor changes. Sigma recommends retrieving the existing representation and basing your changes on that.