Get the code representation of a workbook (Beta)

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.

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.
• You must be the document owner or be granted at least Can view access 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.

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 endpoint to retrieve the workbookId:

1. Go to your Home page.

2. In the navigation menu, select Documents.

3. Click the 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 endpoint like the following:

   List workbooks request format

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

1
{
2
  "entries": [
3
    {
4
      "workbookId": "<workbookId>",
5
      "workbookUrlId": "<workbookUrlId>",
6
      "createdBy": "<userId>",
7
      "updatedBy": "<userId>",
8
      "createdAt": "<timestamp>",
9
      "updatedAt": "<timestamp>",
10
      "name": "<workbookName>",
11
      "url": "<workbookUrl>",
12
      "path": "<folderPath>",
13
      "latestVersion": "<versionNumber>",
14
      "ownerId": "<userId>"
15
    },
16
    {
17
      "workbookId": "<workbookId>",
18
      "workbookUrlId": "<workbookUrlId>",
19
      "createdBy": "<userId>",
20
      "updatedBy": "<userId>",
21
      "createdAt": "<timestamp>",
22
      "updatedAt": "<timestamp>",
23
      "name": "<workbookName>",
24
      "tags": [
25
        {
26
          "versionTagId": "<versionTagId>",
27
          "name": "<tagName>",
28
          "taggedWorkbookId": "<workbookId>",
29
          "workbookTaggedAt": "<timestamp>",
30
          "sourceWorkbookVersion": "<versionNumber>"
31
        }
32
      ],
33
      "url": "<workbookUrl>",
34
      "path": "<folderPath>",
35
      "latestVersion": "<versionNumber>",
36
      "ownerId": "<userId>"
37
    }
38
  ],
39
  "hasMore": <boolean>,
40
  "total": <number>,
41
  "nextPage": null
42
}

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:

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