Manage workbooks as code (Beta)

You can use the Sigma API to retrieve, update, and create workbooks based on a JSON or YAML representation. Using this representation with the Sigma API, you can manage, create, and review workbooks without using the Sigma UI.

Manage workbooks via a code representation 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

You can programmatically manage workbooks using API endpoints that take a JSON or YAML representation of a workbook as input and return it as 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 the API, you can programmatically create and manage dashboards with tables, charts, controls, input tables, layout elements, and actions. 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

Most workbook features and elements can be represented as code, including all table, pivot table, and input table elements, every chart type, all layout elements, controls, themes, panels, agents, and action effects. However, some features and combinations of features are not supported. Consult the following resources for up-to-date information about what features are represented and how to use them:

• To see the full schema definition for the representation, see the Sigma OpenAPI specification.
• To review every element type, property, and value the representation accepts, see the endpoint documentation for Create a workbook.
• For many common features and settings, you can see an example compared with the steps to create it in the UI in the Workbook representation example library.

The following list is non-exhaustive and describes some of the limitations of the current representation:

• Some configurations of supported elements are not represented, such as data entry for input tables.
• Some workbook features are not represented, such as tagged versions of workbooks, workbook comments, and workbook sharing.
• Managing multiple tables with the same name in the same workbook is not supported.
• Some features require an asset to be created in the Sigma UI before it can be referenced in a workbook representation. For example, you must upload an image before you can reference it in a workbook representation. Themes, plugins, CSV tables, and API connectors must also be created in the Sigma UI before they can be referenced in a workbook representation.

Endpoints for managing workbooks as code

Use the following endpoints to retrieve, create, and update the code representation of a workbook. In each case, the representation travels in a contents object:

Get the code representation of an existing workbook

To retrieve the code representation of an existing workbook, call the Get a workbook endpoint with the workbookId for the workbook and the query parameter includeContents=true:

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 a workbook endpoint, passing the workbookId as a path parameter and includeContents=true as a query parameter.

The endpoint returns the workbook metadata, the documentVersion the representation was read from, and the code representation in the contents field. The response is JSON by default. To receive YAML, add the query parameter format=yaml or the header Accept: application/yaml.

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 endpoint with the code representation in the contents field of 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 endpoint, passing the code representation as contents in the request body.

The endpoint creates the workbook and returns the workbookId in the response body. Omit contents to create an empty workbook instead.

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 code representation endpoint with the code representation in the contents field of 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 code representation endpoint, passing the workbookId as a path parameter and the code representation as contents in the request body.

The endpoint updates the workbook.

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

Validate a workbook code representation

To check that a workbook code representation is valid before you create a workbook from it, call the Create a workbook endpoint with dryRun: true in the request body. A dry run validates the representation and confirms that you can create the workbook in the target folder, but does not create the workbook.

1. Prepare the code representation you want to validate.
2. Call the Create a workbook endpoint, passing dryRun: true, the target folderId, the workbook name, and the code representation as contents in the request body. A dry run requires the contents field.

If the representation is valid, the endpoint returns the metadata the workbook would have, plus a warnings array describing any non-fatal issues found in the representation. The fields that only exist after a workbook is created, including workbookId, workbookUrlId, url, createdAt, and updatedAt, are null.

If the representation is invalid, the endpoint returns a 400 response with valid: false, an errors array describing each validation failure, and a warnings array describing non-fatal issues.