Create a workbook from a code representation (Beta)

You can create a workbook from a code representation by calling the Create 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 create a workbook from a code representation. 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.
• The user associated with your API credentials must be assigned an account type with the Create, edit, and publish workbooks permission enabled.

Generate API client credentials and an API access token

Prepare a code representation

To create a workbook using the Create a workbook from a code representation endpoint, you must first construct a valid code representation of a workbook.

📘

To see example representations with various features and configurations, see the Example library.

You can prepare a representation using any of the following options:

• Prepare the representation manually
• Prepare a representation from multiple YAML documents
• Prepare the representation based on an existing workbook

Prepare the representation manually

You can prepare the code representation of a workbook manually by constructing JSON or YAML with the required fields.

A valid representation of a workbook has the following fields:

• name: The name of the workbook.
• schemaVersion: The version of the representation schema to use.
• folderId: The ID of the folder to create the workbook in.
• pages: An array of page objects and their contents.
  • id: An ID for the page.
  • name: The name of the page.
  • elements: An array of element objects and their contents. Can be empty.

💡

Because a valid code representation of a workbook can contain many nested objects with references to one another, Sigma does not recommend preparing large representations manually. See Prepare the representation using an AI assistant and Prepare the representation based on an existing workbook for alternative options to prepare a representation.

As an example, the following POST request creates an empty workbook in a specified folder:

curl --request POST \
    --url <base_url>/v2/workbooks/spec \
    --header "Authorization: Bearer <access_token>" \
    --header 'content-type:application/json' \
    --data '{"name":"Sample Workbook","schemaVersion":1,"folderId":<folderId>,"pages":[{"id":<pageId>,"name":"Page 1","elements":[]}]}'

The representation for the workbook created by that request appears as follows:

{
    "workbookId": <workbookId>,
    "name": "Sample Workbook",
    "url": <workbookUrl>,
    "documentVersion": 1,
    "latestDocumentVersion": 1,
    "ownerId": <userId>,
    "folderId": <folderId>,
    "createdBy": <userId>,
    "updatedBy": <userId>,
    "createdAt": <timestamp>,
    "updatedAt": <timestamp>,
    "schemaVersion": 1,
    "pages": [
        {
            "id": <page_id>,
            "name": "Page 1",
            "elements": []
        }
    ],
    "layout": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"doc-4b9f\"/>\n"
}

💡

The layout field is not required for a successful POST request, but is included in the response when you make a GET request for the representation of the same workbook. For more information on using the layout field to customize a workbook, see Customize the layout of a workbook in code representation.

You can add elements like tables, charts, and more to the representation by including them in the elements array. To learn about the configuration of an element in the representation, see the entry for that element in the Workbook representation example library.

Prepare a representation from multiple YAML documents

When preparing a code representation of a workbook, you can define the workbook contents in multiple YAML documents, and combine them into one workbook when calling the Create a workbook from a code representation endpoint.

As an example, the following POST request creates an empty workbook in a specified folder with two pages, each defined in a separate YAML document:

curl --request POST \
        --url <base_url>/v2/workbooks/spec \
        --header "Authorization: Bearer <access_token>" \
        --header "content-type: application/yaml" \
        --data 'name: Sample Workbook
        schemaVersion: 1
        folderId: <folderId>
        pages:
        - id: <pageId>
            name: Page 1
            elements: []
        ---
        pages:
        - id: <pageId>
            name: Page 2
            elements: []'

The representation for the workbook created by that request appears as follows:

{
    "workbookId": <workbookId>,
    "name": "Sample Workbook",
    "url": <workbookUrl>,
    "documentVersion": 1,
    "latestDocumentVersion": 1,
    "ownerId": <userId>,
    "folderId": <folderId>,
    "createdBy": <userId>,
    "updatedBy": <userId>,
    "createdAt": <timestamp>,
    "updatedAt": <timestamp>,
    "schemaVersion": 1,
    "pages": [
        {
        "id": <page_id>,
        "name": "Page 1",
        "elements": []
        },
        {
        "id": <page_id>,
        "name": "Page 2",
        "elements": []
        }
    ],
    "layout": "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"page-1\"/>\n<Page type=\"grid\" gridTemplateColumns=\"repeat(24, 1fr)\" gridTemplateRows=\"auto\" id=\"page-2\"/>\n"
}

When combining multiple YAML documents in one workbook code representation, each YAML document must represent one array of workbook pages. Each document must contain the top-level pages array, and you cannot combine contents from multiple documents inside one page.

Prepare the representation based on an existing workbook

You can prepare a code representation of a workbook by retrieving the representation of an existing workbook and making changes based on that representation.

🚩

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.

To get the representation of an existing workbook, see Get the code representation of a workbook.

Identify where to create the workbook

To create a workbook from a representation, you must identify the folder to create the workbook in. You can identify a folder and then call the List files endpoint to retrieve the id for the folder:

1. Go to the Sigma Home page.

2. In the navigation menu, select Documents.

3. Click the Document type filter and select Folders.

   The list of your folders appears. If there is no folder for you to create the workbook in, select Create folder to create one.

4. Identify the folder you want to retrieve the id for, by name, creator, or other details.

5. Call the List files endpoint, with a query parameter to filter for folders:

   Get a list of folders request format

   Shell

   curl --request GET \
       --url '<base_url>/v2/files?typeFilters=folder' \
       --header 'Authorization: Bearer <access_token>' \
       --header 'accept:application/json' \
       --header 'content-type: application/x-www-form-urlencoded'

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

   List folders response format

   JSON

   {
       "entries": [
           {
               "id": "<folder_id>",
               "urlId": "<folder_url_id>",
               "name": "<folder_name>",
               "type": "folder",
               "parentId": "<parent_folder_id>",
               "parentUrlId": "<parent_folder_url_id>",
               "permission": "<permission_level>",
               "path": "<folder_path>",
               "badge": null,
               "ownerId": "<owner_user_id>",
               "createdBy": "<creator_user_id>",
               "updatedBy": "<updater_user_id>",
               "createdAt": "<creation_timestamp>",
               "updatedAt": "<update_timestamp>",
               "isArchived": false
           }
       ],
       "total": <total_number_of_folders>,
       "nextPage": null
   }

6. Using the name or other details you identified in step 4, find the folder you want to retrieve the id for, and copy the id from the response body.

7. Add the folder id to the code representation you prepared earlier as the folderId.

Call the Create a workbook from a code representation endpoint

Using the access token and code representation you prepared in the previous steps, make a POST request to the Create a workbook from a code representation endpoint using the following format:

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

The endpoint creates the workbook and returns the workbookId in the response body.