This QuickStart demonstrates how to enhance embedded Sigma workbooks with custom description functionality. Since Sigma's API doesn't natively support workbook descriptions, we'll implement a local storage solution using lowdb to enable users to add, edit, and delete contextual information directly within the embedded environment.
The pattern shown here can be extended to store any custom metadata—usage notes, business context, data lineage information, or other supplementary details that help users understand and effectively utilize workbook content.
REST API Usage 01: Getting Started
For more information on Sigma's product release strategy, see Sigma product releases
If something doesn't work as expected, here's how to contact Sigma support
Target Audience
Developers who want to use Sigma's REST API to programmatically control Sigma in an embedded context.
Prerequisites
- Any modern browser will work.
- Access to your Sigma environment.
- Some familiarity with Sigma is assumed. Not all steps are shown, as the basics are assumed understood.
- Microsoft VSCode or other suitable development tool.
If you haven't already, open the project in VSCode and start a terminal session and navigate to the folder embedding_qs_series_2_api_use_cases in terminal.
The only extra thing we need to do is install a local database that will be used to store extended workbook description information. We will use a version of lowdb that supports commonJS for this.
Run the following command in terminal:
npm install lowdb@1.0.0
Lowdb installs really quickly:
The git repository already contains a Data folder with the required wb-descriptions.json file. The data file is initially empty except for:
{
"workbookDescriptions": []
}
Database schema
The system maintains the local lowdb database in the wb-descriptions.json file storing:
{
"workbookDescriptions": [
{
"workbookId": "0e51172a-a4c0-4954-8c8c-9d854dcf4434",
"workbookUrlId": "r0WXMPpc0YtQCTFR7CdDK",
"workbookName": "Embed_API_QuickStart",
"description": "Plugs Sales Information",
"createdBy": "build.embed.qs@example.com",
"updatedBy": "build.embed.qs@example.com",
"createdAt": "2025-07-28T16:26:57.802Z",
"updatedAt": "2025-07-28T16:26:57.802Z"
}
]
}
Start the Express server in terminal from the embedding_qs_series_2_api_use_cases folder and enable debugging:
DEBUG=true npm start
The server is ready when it displays: Server listening at http://localhost:3000.
Browse to the landing page:
http://localhost:3000
Select the Set Workbook Description page and click Go.
Select the Embed_API_QuickStart workbook:
The embed loads and there is a Workbook Description button provided.
Click the Workbook Description button to access the modal.
Enter some text for the description:
Click Save.
A popup will confirm the description was created with Workbook description saved successfully!.
Click Ok to close that.
We are returned to the page and the description is placed below the page title:
Confirm in the local database that the description has been created there:
Deleting descriptions
If the selected workbook has an existing description, it can be updated or deleted by clicking the Workbook Description button again. Since one already exists, we display a Delete option and the Save button is labeled Update:
In this QuickStart, we demonstrated how to enhance embedded Sigma workbooks with custom description capabilities using local storage. We covered implementing a complete description management system that allows users to create, update, and delete workbook descriptions directly within the embedded environment.
This approach provides a foundation for extending embedded workbooks with custom metadata storage, enabling richer context and documentation without requiring modifications to the underlying Sigma workbook structure.
Additional Resource Links
Blog
Community
Help Center
QuickStarts
Be sure to check out all the latest developments at Sigma's First Friday Feature page!
