> 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.

# Get the code representation of a workbook (Beta)

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 retrieve a code representation of an existing workbook by calling the Get the code representation of a workbook endpoint with the `workbookId` for the workbook.

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

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.

## User requirements

The ability to create 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).
* You must be the document owner or be granted at least **Can view** [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 workbook ID

To retrieve the code representation of an existing workbook, you must know the unique `workbookId` for that workbook. After you identify the workbook you want to retrieve the representation for, 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 <img src="https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg" alt="" /> **Document type** filter and select **wWorkbooks**.

   The list of your workbooks appears.

4. Identify the workbook you want to retrieve the representation for by name, owner, or other details.

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

   ```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:

```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 retrieve the representation for, and copy the `workbookId` to pass to the Get the code representation of a workbook endpoint.

## Retrieve the representation

Using the `workbookId`, make a GET request to the Get the code representation of a workbook endpoint using the following format:

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

The response body contains a JSON representation of the workbook for the specified `workbookId`.

To see an example of a workbook representation along with the instructions used to create it in the Sigma UI, see [Example representation: Workbook with a table](/docs/example-representation-workbook-with-a-table).