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

# Update a workbook from a code representation (Beta)

> Update an existing Sigma workbook from a JSON or YAML code representation using the Sigma API Update workbook from code endpoint.

This documentation describes one or more private 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).

If you are interested in joining a limited test group and enabling this feature in your Sigma organization, [contact Support](/docs/sigma-support) or reach out to your Account Executive.

You can update an existing workbook from a code representation by calling the Update a workbook from a code representation endpoint with the code representation in the request body.

This document provides step-by-step instructions for using this endpoint to update a workbook from a code representation. For more information on working with workbooks programmatically, see [Manage workbooks as code](/docs/manage-workbooks-as-code).

## User requirements

The ability to update a workbook from a code representation requires the following:

* 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.
* You must be the document owner or be granted **Can edit** [access](/docs/folder-and-document-permissions) to the workbook.

## Generate API client credentials and an API access token

To start, you must generate credentials for the Sigma API. These credentials are used to retrieve an access token, which is required to make requests to the API.

For step-by-step instructions on generating developer credentials in Sigma and using them to authenticate to the Sigma API, see the instructions in [Generate client credentials](/reference/generate-client-credentials).

## Identify the workbook and retrieve the workbookId

To update an existing workbook from a code representation, you must know the unique `workbookId` for that workbook. After you identify the workbook you want to update, you can call the [List workbooks](/reference/list-workbooks) endpoint to retrieve the `workbookId`:

1. Go to your **Home** page.

2. In the navigation menu, select **Documents**.

3. Click the **Document type** <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg" alt="" /> filter and select **Workbooks**.

   The list of your workbooks appears.

4. Identify the workbook you want to update, by name, owner, or other details.

5. Make a GET request to the [List workbooks](/reference/list-workbooks) endpoint like the following:

   #### List workbooks request format

   ```shell
   curl --request GET \
        --url <base_url>/v2/workbooks \
        --header 'Authorization: Bearer <access_token>' \
        --header 'accept:application/json' \
        --header 'content-type: application/x-www-form-urlencoded'
   ```

   The response includes a list of workbooks in your organization, in the following format:

   #### List workbooks response format

   ```json
   {
     "entries": [
       {
         "workbookId": "<workbookId>",
         "workbookUrlId": "<workbookUrlId>",
         "createdBy": "<userId>",
         "updatedBy": "<userId>",
         "createdAt": "<timestamp>",
         "updatedAt": "<timestamp>",
         "name": "<workbookName>",
         "url": "<workbookUrl>",
         "path": "<folderPath>",
         "latestVersion": "<versionNumber>",
         "ownerId": "<userId>"
       },
       {
         "workbookId": "<workbookId>",
         "workbookUrlId": "<workbookUrlId>",
         "createdBy": "<userId>",
         "updatedBy": "<userId>",
         "createdAt": "<timestamp>",
         "updatedAt": "<timestamp>",
         "name": "<workbookName>",
         "tags": [
           {
             "versionTagId": "<versionTagId>",
             "name": "<tagName>",
             "taggedWorkbookId": "<workbookId>",
             "workbookTaggedAt": "<timestamp>",
             "sourceWorkbookVersion": "<versionNumber>"
           }
         ],
         "url": "<workbookUrl>",
         "path": "<folderPath>",
         "latestVersion": "<versionNumber>",
         "ownerId": "<userId>"
       }
     ],
     "hasMore": <boolean>,
     "total": <number>,
     "nextPage": null
   }
   ```

6. Identify the workbook you want to update, and copy the `workbookId` to use with the Update a workbook from a code representation endpoint.

## Prepare the representation

To update an existing workbook from a code representation, you must prepare a valid code representation of the workbook with the updates you want to apply. You can base this on the existing workbook's representation, or construct an entirely new one.

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.

The code representation you prepare can be passed into the request body of the Update a workbook from a representation endpoint to update the workbook.

1. Using the `workbookId` you identified in the previous section, follow the instructions in [Retrieve the code representation](/docs/get-the-code-representation-of-a-workbook) to get the current representation.

   For example, you might retrieve the representation for a workbook with a single table, like the following:

   #### YAML representation

   ```yaml
   name: table
   schemaVersion: 1
   pages:
   - id: jgZnqiZGOh
       name: Page 1
       elements:
       - id: z8NmRPjbEN
           kind: table
           source:
           connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
           kind: warehouse-table
           path:
               - FUN
               - BIKES
               - TRIP
           columns:
           - id: Y3BEzKB09f
               formula: '[TRIP/Id]'
           - id: qQ09VyFetR
               formula: '[TRIP/Duration]'
           - id: n2weGZ6GfF
               formula: '[TRIP/Start Date]'
           - id: jWEvA87YUH
               formula: '[TRIP/Start Station Name]'
           - id: D8c5YVgpsZ
               formula: '[TRIP/Start Station Id]'
           - id: r3pku8OHAS
               formula: '[TRIP/End Date]'
           - id: fjSITWU8RE
               formula: '[TRIP/End Station Name]'
           - id: rsndxYRmfw
               formula: '[TRIP/End Station Id]'
           - id: ujOO9jaUuB
               formula: '[TRIP/Bike Id]'
           - id: vQL0WpcDi6
               formula: '[TRIP/Subscription Type]'
           - id: 8nEosRvuru
               formula: '[TRIP/Zip Code]'
           order:
           - Y3BEzKB09f
           - qQ09VyFetR
           - n2weGZ6GfF
           - jWEvA87YUH
           - D8c5YVgpsZ
           - r3pku8OHAS
           - fjSITWU8RE
           - rsndxYRmfw
           - ujOO9jaUuB
           - vQL0WpcDi6
           - 8nEosRvuru
   layout: |
   <?xml version="1.0" encoding="utf-8"?>
   <Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
       <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
   </Page>
   ```

2. Make any desired changes to the representation. For example, you might want to rename the workbook, rename a table, or add a new column.

The workbook code representation does not support all workbook features. Unsupported features are silently dropped when you make a request to the Get the code representation of a workbook endpoint. If you use a representation from that endpoint to create or update another workbook from code, it does not include the dropped features, even if they were present in the original workbook.

In this example, most columns are removed from the representation, leaving only the *Id* and *Duration*:

#### YAML representation

```yaml
name: table
schemaVersion: 1
pages:
- id: jgZnqiZGOh
    name: Page 1
    elements:
    - id: z8NmRPjbEN
        kind: table
        source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
            - FUN
            - BIKES
            - TRIP
        columns:
        - id: Y3BEzKB09f
            formula: '[TRIP/Id]'
        - id: qQ09VyFetR
            formula: '[TRIP/Duration]'
        order:
        - Y3BEzKB09f
        - qQ09VyFetR
layout: |
<?xml version="1.0" encoding="utf-8"?>
<Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
    <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
</Page>
```

## Call the Update a workbook from a code representation endpoint

Finally, call the Update a workbook from a code representation endpoint, passing the `workbookId` as a path parameter and the updated code representation in the request body. The request format is as follows:

#### Update a workbook from a representation request format

```shell
curl --request PUT \
    --url <base_url>/v2/workbooks/<workbookId>/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type: application/json' \
    --data '<representation>'
```

This example request replaces the example representation shown after step 1 of the previous section with the truncated representation from step 2:

#### Update a workbook from a representation request example

```shell
curl --request PUT \
    --url <base_url>/v2/workbooks/<workbookId>/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type: application/yaml' \
    --data 'name: table
schemaVersion: 1
pages:
- id: jgZnqiZGOh
    name: Page 1
    elements:
    - id: z8NmRPjbEN
        kind: table
        source:
        connectionId: 6944db1a-f9f0-496f-91ba-4781e7f0490d
        kind: warehouse-table
        path:
            - FUN
            - BIKES
            - TRIP
        columns:
        - id: Y3BEzKB09f
            formula: "[TRIP/Id]"
        - id: qQ09VyFetR
            formula: "[TRIP/Duration]"
        order:
        - Y3BEzKB09f
        - qQ09VyFetR
layout: |
<?xml version="1.0" encoding="utf-8"?>
<Page type="grid" gridTemplateColumns="repeat(24, 1fr)" gridTemplateRows="auto" id="jgZnqiZGOh">
    <LayoutElement elementId="z8NmRPjbEN" gridColumn="1 / 25" gridRow="1 / 21"/>
</Page>
'
```

The endpoint updates the workbook with the new representation.