> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/docs/manage-workbooks-as-code/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Manage workbooks as code (Beta)

> Use the Sigma API to create, update, and retrieve workbooks as JSON or YAML for programmatic dashboards, automation, and AI development.

> **Note**
>
> This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page.
>
> This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see [Beta features](/docs/sigma-product-releases#beta-features).

You can use the Sigma API to retrieve, update, and create [workbooks](/docs/workbooks-overview) 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](#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](/docs/folder-and-document-permissions) to the workbook.
* You must have developer credentials for the Sigma API. For more information, see [Get started with the Sigma REST API](/reference/get-started-sigma-api).
* The user associated with your API credentials must be assigned an [account type](/docs/create-and-manage-account-types) 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](https://assets.sigmacomputing.com/openapi/public-rest-api/sigma-computing-public-rest-api.json).
* To review every element type, property, and value the representation accepts, see the endpoint documentation for [Create a workbook](/reference/create-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](/docs/workbook-representation-example-library).

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

* Some configurations of supported features are not represented, such as data entry for input tables and HMAC authentication for action sequences with a webhook trigger.
* 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.
* If the columns in the data source of a custom SQL element change, you must run the custom SQL element in the UI before it can be referenced in a code representation again.
* 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:

| Task                                    | Endpoint                                                                                                                        |
| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| Retrieve a representation               | [Get a workbook](/reference/get-workbook) (`GET /v2/workbooks/{workbookId}?includeContents=true`)                               |
| Create a workbook from a representation | [Create a workbook](/reference/create-workbook) (`POST /v2/workbooks`)                                                          |
| Update a workbook from a representation | [Update a workbook from a code representation](/reference/update-workbook-contents) (`PUT /v2/workbooks/{workbookId}/contents`) |
| Validate a representation               | [Create a workbook](/reference/create-workbook) with `dryRun: true` (`POST /v2/workbooks`)                                      |

## Get the code representation of an existing workbook

To retrieve the code representation of an existing workbook, call the [Get a workbook](/reference/get-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](/reference/list-workbooks) endpoint to retrieve the `workbookId` for the workbook.
3. Call the [Get a workbook](/reference/get-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)](/docs/get-the-code-representation-of-a-workbook).

## Create a workbook from a code representation

To create a workbook from a code representation, call the [Create a workbook](/reference/create-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](/docs/workbook-representation-example-library).
2. Call the [Create a workbook](/reference/create-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](/docs/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](/reference/update-workbook-contents) 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](/reference/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](/docs/workbook-representation-example-library).
4. Call the [Update a workbook from a code representation](/reference/update-workbook-contents) 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](/docs/update-a-workbook-from-a-code-representation).

> **Note**
>
> The [Update a workbook from a code representation](/reference/update-workbook-contents) 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.

## 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](/reference/create-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](/reference/create-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.

> Official documentation and guidance for using Sigma to build AI apps, dashboards, and agents on governed warehouse data.

## Docs

- [Get the code representation of a workbook (Beta)](https://help.sigmacomputing.com/docs/get-the-code-representation-of-a-workbook.md): Retrieve a Sigma workbook as JSON or YAML code by calling the API Get a workbook endpoint with includeContents=true.
- [Create a workbook from a code representation (Beta)](https://help.sigmacomputing.com/docs/create-a-workbook-from-a-code-representation.md): Create a Sigma workbook from a JSON or YAML code representation using the Sigma API Create workbook endpoint.
- [Update a workbook from a code representation (Beta)](https://help.sigmacomputing.com/docs/update-a-workbook-from-a-code-representation.md): Update an existing Sigma workbook from a JSON or YAML code representation using the Sigma API Update workbook contents endpoint.
- [Customize the layout of a workbook in code representation (Beta)](https://help.sigmacomputing.com/docs/customize-the-layout-of-a-workbook-in-code-representation.md): Customize Sigma workbook page layout in code using the layout field, an XML string that positions elements on a 24-column grid.