diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_10.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_10.png
index 1ea79744..6dc9cf08 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_10.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_10.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_11.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_11.png
index 3622fd3b..59c99352 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_11.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_11.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_12.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_12.png
index 1ea4da8e..7ca6d511 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_12.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_12.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_13.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_13.png
index a44d2a6f..c1d408fc 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_13.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_13.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_14.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_14.png
index 3489112b..1ddf8590 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_14.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_14.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_15.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_15.png
index 4d46c511..42d49ee1 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_15.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_15.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_3.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_3.png
index 9ccc72f9..c2495cb0 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_3.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_3.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_6.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_6.png
index 10b47d35..fd73a92b 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_6.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_6.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_9.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_9.png
index 1cc004d3..7134a1c0 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_9.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/eapi_9.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_26.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_26.png
index 4f8714a4..52e18452 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_26.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_26.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_27.png b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_27.png
index 6a1b7883..c42e08a2 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_27.png and b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/assets/gs_27.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/embedding_rest_api_usage_01_getting_started.md b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/embedding_rest_api_usage_01_getting_started.md
index 942a6c23..7c1e18e9 100644
--- a/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/embedding_rest_api_usage_01_getting_started.md
+++ b/site/sigmaguides/src/embedding_rest_api_usage_01_getting_started/embedding_rest_api_usage_01_getting_started.md
@@ -6,7 +6,7 @@ environments: web
status: Published
feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues
tags: default
-lastUpdated: 2025-07-14
+lastUpdated: 2025-07-21
# REST API Usage 01: Getting Started
@@ -259,16 +259,16 @@ Ensure you are in the project folder:
pwd
```
-
+
-Once in the correct folder, we can start the web server with:
+Once in the correct folder, we can start the web server with: debugging enabled:
```code
-npm start
+DEBUG=true npm start
```
-Some debug information is provided and the expected result is:
+Detailed debug information is provided when `DEBUG=true` is enabled and the expected result is:
-
+
Once the server is running, we can browse to a preconfigured provisioning page. This page adds our two embed test users and displays the `memberId` for each, along with the admin user specified in .env (based on the provided email address):
@@ -359,7 +359,7 @@ We last left the browser open the main landing page. If for some reason it all g
Restart it as shown earlier, ensuring you're in the correct project folder:
```code
-npm start
+DEBUG=true npm start
```
The server is ready when it displays `Server listening at http://localhost:3000`.
@@ -373,60 +373,46 @@ Browse to the landing page:
http://localhost:3000
```
-Select `API Getting Started` QuickStart and click `Go`:
+Select `Getting Started` QuickStart and click `Go`:
The `API Getting Started` page comes with a side-panel that displays embedding and token details.
-The actual token appears lower on the side panel for anyone who wants to validate it using a third-party site such as [JWT.io](https://jwt.io/):
+The actual token appears lower on the side panel for anyone who wants to validate it using a third-party site such as [JWT.io](https://jwt.io/).
+
+There is also a `README` button, that provides detailed information about how the `Getting Started` page is constructed, endpoints users and other useful information:
+
+IMPORTANT: We will rely on the information in the README for the implementation details and not discuss them in this QuickStart. A button is provided on the webpage for easy access.
+
+
You can select to operate as either embed user and also select from our test workbooks:
-
+
+
+We have now successfully embedded Sigma into our host application and used the API to get information from Sigma (workbooks in the Embed_Users workspace) and passed the selected workbook back to Sigma using the correct format for a workbook embed:
-The terminal console displays logging output each time a page with an embed is reloaded:
+Because we have debugging enabled, the terminal console displays logging output each time a page with an embed is reloaded:
-Note that the token is cached, and the embed URL is also displayed.
+
+NOTE: The JWT is provided along with the embed URL should debugging be required.
+
Sigma supports different embed URL formats depending on the content type for different embeds in Sigma and this example constructs the correct format for embedding a `workbook` in the code.
For more information, see [What URL to use](https://help.sigmacomputing.com/docs/create-an-embed-api-with-json-web-tokens#what-url-to-use)
-We have now successfully embedded Sigma into our host application and used the API to get information from Sigma (workbooks in the Embed_Users workspace) and passed the selected workbook back to Sigma using the correct format for a workbook embed:
-
-
-
### Enabling Menus and Folder Navigation for Build Users
We have designed the project to allow the `Build` user to see the Sigma menu and folder navigation, placing them at the top of the embed:
-This was done to demonstrate a few of the optional runtime parameters that are available in the JWT embed. The full list is included (at the time of this QuickStart) in the `.env` file:
-```code
-# -----------------------------------------------------------------------------
-# OPTIONAL EMBED PARAMETERS (defaults are shown)
-disable_auto_refresh=false
-disable_mobile_view=false
-hide_folder_navigation=false
-hide_menu=false
-hide_page_controls=false
-hide_reload_button=false
-hide_title=false
-hide_tooltip=false
-hide_view_select=false
-lng=English
-menu_position=none
-page_id=
-responsive_height=false
-theme=Lite
-view_id=
-# -----------------------------------------------------------------------------
-```
+This was done to demonstrate a few of the optional runtime parameters that are available in the JWT embed. All the parameters (at the time of this QuickStart) are included in the `.env` file.
To give the `Build` user access to Sigma’s editing tools during embedding, we configure the JWT to include specific UI flags. These values are only applied when embedding an entire workbook (not a page or element):
```code
@@ -442,7 +428,11 @@ These settings ensure that:
- The menu appears at the top of the screen (instead of a side menu)
- The user can navigate folders within Sigma if allowed by their role
-We apply these settings at runtime only if the selected user is a `Build` user. `View` users receive a more restricted UI by default.
+We apply these settings at runtime only if the selected user is a `Build` user. We intentionally enforce `View` users receiving a more restricted UI by default.
+
+Selecting the `View` user, we can see the menu bar options are not included in the embed:
+
+
IMPORTANT: Optional parameters provide fine-grained control over what embedded users can see and do.
@@ -456,7 +446,7 @@ In this example, we chose to give Build users greater access than View users by
## Constructing Embed URLs
Duration: 5
-Return to the landing page and select `API Embed Control` and click `Go`.
+Return to the landing page and select `Embed Controls` and click `Go`.
This page extends the previous functionality to include an `Embed Type` selector. You can choose to select the workbook, page or element for the selected workbook.
@@ -483,252 +473,49 @@ The construction of the Sigma embed URLs happens in the file `helpers/build-embe
It is responsible for constructing the embed URLs based on `embedType`, `workbookUrlId`, and optional `targetId`.
-Here's what it does:
-
-**For workbook:**
-https://{orgSlug}.sigmacomputing.com/embed/workbook/{workbookUrlId}
-
-**For page:**
-https://{orgSlug}.sigmacomputing.com/embed/page/{workbookUrlId}/{pageId}
-
-**For element:**
-https://{orgSlug}.sigmacomputing.com/embed/element/{workbookUrlId}/{pageId}:{elementId}
-
-This file is used by the `/generate-jwt/:mode` route handler, defined in `routes/api/generate-jwt.js`, to construct the final embed URL that gets returned to the frontend.
-
-This allows the user to select any workbook, page or element to embed while dynamically building the embed URL.
-
-Let's look at the rest of the core files in the next section.
-
-
-
-
-## Project Code
-Duration: 5
-
-This project follows a [Separation of Concerns (SoC) design pattern](https://en.wikipedia.org/wiki/Separation_of_concerns) to keep the codebase organized and maintainable.
-
-Routes handle HTTP requests and define API endpoints. They control what happens when a request reaches a specific URL.
-
-Helpers are reusable utility functions that encapsulate logic shared across routes — such as formatting data, building embed URLs, or calling Sigma’s APIs.
-
-By separating these responsibilities, the code becomes easier to read, test, and update — especially as the application grows.
-
-Here’s a summary of key project files and their roles:
-
-### Helpers Folder
-Contains backend utility scripts for interacting with the Sigma API and generating JWTs.
-- **build-embed-url.js:** Constructs a valid Sigma embed URL based on inputs.
-- **create-jwt.js:** Generates a signed JWT based on user input and environment values.
-- **get-access-token.js:** Authenticates against Sigma API to get a bearer token.
-- **get-workbook-metadata.js:** Fetches detailed metadata (e.g., pages/elements) for a workbook.
-- **get-workbooks.js:** Retrieves the list of workbooks the API user can access.
-- **provision.js:** Provisions users into Sigma (e.g., for impersonation or setup).
-
-### Public Folder:
-
-- **index.html:** Main landing page for the project. Lists / links to each QuickStart and provisioning page.
-
-#### api-getting-started Folder
-- index.html: First QuickStart in the series; lets users pick a user/workbook and embed a workbook (only).
-
-#### api-embed-controls Folder
-- **index.html:** Web page with controls for user, workbook, embed type, and page/element.
-
-#### tools Folder
-- **preload-users.html:** Standalone page for provisioning users before embedding.
-
-### Routes Folder
-These files define the Express route handlers that the front end calls. Each route uses a helper to interact with the Sigma API and return filtered results to the client.
-
-**generate-jwt.js:**
-Handles requests to `/generate-jwt/:mode`.
-
-- Receives the selected user type (view or build) and embed type (workbook, page, or element) from the front-end.
-- Calls `build-embed-url.js` to construct the proper Sigma embed URL.
-- Calls `create-jwt.js` to sign the token with your secret.
-
-Returns the final embed URL and JWT to the front end.
-
-**elements.js:**
-Handles requests to `/api/elements?workbookUrlId={id}&pageId={id}`.
-
-- Calls get-workbook-metadata.js to fetch metadata for the workbook.
-- Extracts the specified page.
-- Filters and returns only embeddable elements (e.g., type = visualization or table).
-- Designed for use when embedding a specific element.
-
-**pages.js:**
-Handles requests to `/api/pages?workbookUrlId={id}`.
-
-- Calls `get-workbook-metadata.js` to fetch metadata for the specified workbook.
-- Returns a flat list of pages (pageId, name) for populating the Page dropdown.
-
-**workbooks.js:**
-Handles requests to `/api/workbooks`.
-
-- Calls `get-workbooks.js` (helper) to fetch all accessible workbooks via the Sigma API.
-- Optionally filters by folder path or naming pattern (done client-side).
-- Used to populate the Workbook dropdown.
-
-**provision-users.js:**
-Handles requests to /api/provision-users. Stored in the `routes` folder.
-
-- Receives a request payload with user email, name, and role.
-- Calls functions from `helpers/provision.js`:
-- lookupMemberId() checks if the user exists.
-- provisionEmbedUser() creates a new embed user and assigns them to the "Embed_Users" team.
-- Returns the memberId to the frontend.
-
-### Server Folder
-Contains the Express server setup for the project. It initializes middleware, loads environment variables, and defines the main entry point for running the backend. Acts as the bridge between API routes, helpers, and the front-end interface.
-
-- Loads .env configuration using dotenv.
-- Sets up and configures the Express server.
-- Applies JSON parsing middleware.
-- Mounts all API route handlers from routes/api/.
-- Serves static files from the public/ directory (used for serving the HTML pages).
-- Defines the port and starts the server.
-
-
-
-
-## Endpoints Operations Used
-Duration: 5
-
-The following is information regarding a few of the primary API endpoints used to enable the functionality demonstrated.
-
-The JWT token process has previously been detailed in the QuickStart: [Embedding 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_01_getting_started_v3/index.html?index=..%2F..index#0), so we won't cover that here.
-
-### Sigma API Endpoints Used
-
-| Endpoint | Purpose | Method |
-|----------------------------------|---------------------------------|--------|
-| `/v2/members?search=...` | Check if user exists (see note) | `GET` |
-| `/v2/teams?name=...` | Look up team ID by name | `GET` |
-| `/v2/members?sendInvite=false` | Provision embed user | `POST` |
-| `/v2/workbooks` | List workbooks | `GET` |
-| `/v2/workbooks/{workbookId}` | Get workbook pages/elements | `GET` |
-
-
-NOTE: /v2/members?search= is a supported query parameter for checking if a user exists, even though it may not appear in Swagger documentation.
-
-
-### User Provisioning
-Provisioning uses a helper script, `helpers/provision.js` that uses the Sigma REST API to provision embed users, assign them to a team, or look them up by email if they already exist.
-
-#### getTeamIdByName(teamName)
-Looks up a team ID by its name (e.g., "Embed_Users"). This is required because Sigma API calls for assigning users to teams require the team's internal teamId, not its display name.
-
-- Endpoint: GET /v2/teams?name=Embed_Users
-- Auth: Bearer token
-- Response: Returns the first matching team and caches it in memory to reduce redundant requests.
-
-#### lookupMemberId(email)
-Checks whether a user already exists before attempting to provision them.
-
-- Endpoint: GET /v2/members?search=email@example.com
-- Response: Returns the memberId if found, or throws an error if none is found.
-
-#### provisionEmbedUser(email, firstName, lastName, memberType)
-Provisions a new Sigma embed user, or returns the existing `memberId` if the user already exists.
-
-- Endpoint: POST /v2/members?sendInvite=false
-- Payload:
-``` json
-json
-Copy
-Edit
-{
- "userKind": "embed",
- "memberType": "viewer" | "explorer",
- "email": "view2.embed.qs@example.com",
- "firstName": "View",
- "lastName": "User",
- "addToTeams": [{ "teamId": "...", "isTeamAdmin": false }],
- "isGuest": false
-}
-```
-
-- Response: Returns the memberId of the new or existing user.
-
-If the API returns a 409 Conflict because the user already exists, the code extracts and returns the existing memberId from the error message.
-
-### Fetching Workbooks
-The helper file, `helpers/get-workbooks.js`, retrieves the list of workbooks that the authenticated user has access to. It's used to populate the Workbook dropdown in the QuickStart UI. All filtering is performed client-side in your helper logic, based on the path or name field.
-
-- Endpoint: GET /v2/workbooks
-
-- Response Structure
-A successful response returns an array like:
-```json
-{
- "entries": [
- {
- "workbookId": "b4a6...68b",
- "name": "Embed_API_QuickStart",
- "path": ["QuickStarts", "Embed", "Embed_API_QuickStart"],
- "url": "https://.../workbook/b4a6...68b",
- ...
- }
- ]
-}
+The customization is done here:
+```code
+ let path;
+ if (embedType === "workbook") {
+ if (!workbookName) throw new Error("Missing workbookName for workbook embed");
+ path = `/workbook/${workbookName}-${workbookUrlId}`;
+ } else if (embedType === "page") {
+ if (!workbookName || !pageId) throw new Error("Missing workbookName or pageId for page embed");
+ path = `/workbook/${workbookName}-${workbookUrlId}/page/${pageId}`;
+ } else if (embedType === "element") {
+ if (!workbookName || !pageId || !elementId)
+ throw new Error("Missing required info for element embed");
+ path = `/workbook/${workbookName}-${workbookUrlId}/element/${elementId}`;
+ } else {
+ throw new Error(`Unsupported embedType: ${embedType}`);
+ }
```
-The route, `/routes/api/workbooks` calls this helper.
+This code block builds a URL path for embedding a Sigma workbook, page, or element based on the value of `embedType`.
-The HTML/JS frontend uses the response to:
-- Filter workbooks by folder or name (if needed).
-- Populate the Workbook dropdown.
-- Store the workbookUrlId() (parsed from the URL) for use in other API calls.
+**let path;**
+Declares the variable that will store the constructed path.
-### Fetching Workbook Metadata (Pages and Elements)
-The helper file, `helpers/get-workbook-metadata.js` retrieves the full metadata for a specific workbook, including its pages and the elements on each page. It powers the dynamic page and element selectors in the UI after a workbook is selected.
+**If embedType === "workbook"**
+Requires workbookName.
+Constructs a URL like: `/workbook/{workbookName}-{workbookUrlId}`
-It supports both:
-- Listing pages for the selected workbook
-- Listing elements on a specific page (typically used for "element" embed types)
+**If embedType === "page"**
+Requires workbookName and pageId.
+Constructs a URL like: `/workbook/{workbookName}-{workbookUrlId}/page/{pageId}`
-- Endpoint: GET /v2/workbooks/{workbookId}
+**If embedType === "element"**
+Requires workbookName, pageId, and elementId.
+Constructs a URL like: `/workbook/{workbookName}-{workbookUrlId}/element/{elementId}`
-**workbookId (string, required):** The short-form ID of the workbook (e.g., b4a6...68b), extracted from the workbook's URL.
+**Else (unsupported embedType)**
+Throws an error indicating the value is not supported.
-- Response Structure
+For additional information about the `Embed Controls` project files, refer to the readme using the button or browse to:
```code
-{
- "workbookId": "...",
- "name": "...",
- "pages": [
- {
- "pageId": "...",
- "name": "Page 1",
- "elements": [
- {
- "elementId": "...",
- "name": "Quantity by Product Type",
- "type": "visualization"
- },
- ...
- ]
- },
- ...
- ]
-}
+http://localhost:3000/api-embed-controls/README.md
```
-The helper flattens the response into:
-- A list of pages (each with pageId and name)
-- For a specific page, a list of elements (each with elementId, name, and type)
-
-This helper is called via these routes:
-- /api/pages?workbookUrlId={id} → Returns list of pages
-- /api/elements?workbookUrlId={id}&pageId={id} → Returns list of elements on a page
-
-Used by the front end UI to:
-- Populate the Page dropdown (for page or element embedding)
-- Populate the Element dropdown (if the "element" type is selected)
-- Filter elements by supported type (visualization, table)
-

diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_01.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_01.png
index acebc595..0b5a2ac9 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_01.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_01.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_02.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_02.png
index d4d5a6fc..e8e65d70 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_02.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_02.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_03.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_03.png
index 013e1fea..05c4b650 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_03.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_03.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_06.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_06.png
index e9375c29..d202a813 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_06.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_06.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_08.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_08.png
index 2d517921..f98f6caa 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_08.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_08.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_09.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_09.png
index b66e7f2d..3fed07a8 100644
Binary files a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_09.png and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_09.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_11.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_11.png
new file mode 100644
index 00000000..bb53b0ca
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_11.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_12.png b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_12.png
new file mode 100644
index 00000000..b3d54fa2
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/assets/api_bm_12.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/embedding_rest_api_usage_02_bookmarks.md b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/embedding_rest_api_usage_02_bookmarks.md
index 5d08167e..1406a473 100644
--- a/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/embedding_rest_api_usage_02_bookmarks.md
+++ b/site/sigmaguides/src/embedding_rest_api_usage_02_bookmarks/embedding_rest_api_usage_02_bookmarks.md
@@ -6,9 +6,9 @@ environments: web
status: published
feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues
tags: default
-lastUpdated: 2025-07-14
+lastUpdated: 2025-07-21
-# Rest API Usage 02: Bookmarks
+# REST API Usage 02: Bookmarks
## Overview
Duration: 5
@@ -23,7 +23,7 @@ This approach enables more personalized, collaborative analytics experiences. It
IMPORTANT: This QuickStart builds on the setup from "REST API Usage 01: Getting Started". If you haven’t yet cloned the repo, installed dependencies, and configured your Sigma workspace, please follow that QuickStart first.
-[REST API Usage 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_rest_api_usage_01_getting%20started_started/index.html?index=..%2F..index#0)
+[REST API Usage 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_rest_api_usage_01_getting_started/index.html?index=..%2F..index#0)
IMPORTANT: Some screens in Sigma may appear slightly different from those shown here. This is because Sigma continuously adds and enhances functionality. Rest assured—Sigma’s intuitive interface ensures that any differences won’t prevent you from completing the QuickStart successfully.
@@ -64,7 +64,7 @@ Duration: 5
If you haven't already, open the project in VSCode and start the Express server in terminal from the `embedding_qs_series_2_api_use_cases` folder:
```code
-npm start
+DEBUG=true npm start
```
The server is ready when it displays: `Server listening at http://localhost:3000`.
@@ -86,54 +86,48 @@ The embed loads but there are no bookmarks in the `Saved Bookmark` list yet. The
### Create a bookmark
-Let's say the `View` user has requested for the workbook only to show data for mobile phones. With this embed configuration, the `Build` user can provide that by creating a bookmark.
+Let's say the `View` user has requested that the workbook only show data for mobile phones. With this embed configuration, the `Build` user can provide that by creating a bookmark.
-Switching to the `Build` user, we can set a filter on the table to display only rows with `Project Types`:
+Switching to the `Build` user, we can set a filter on the table to display only rows with `Product Types` > `Mobiles`:
-...that are `Mobiles`:
-
-
+
+NOTE: The "Bookmark Name" control appears when an explore is first created.
+
-A few things happen when we start to interact with the table, in this case selecting a column to filter on (Product Type) and then selecting a value (Mobiles).
+A few things happen when we start to interact with the table. In this case, we're selecting a column to filter on (Product Type) and then selecting a value (Mobiles).
-In the console log we can see that each time, a different `exploreKey` event was emitted from Sigma. This is an important observation as we only really want to create a bookmark on the most recent `exploreKey` and this needs to be handled in the code:
+In the console log, we can see that each time a different `exploreKey` event was emitted from Sigma. This is an important observation, as we only want to create a bookmark on the most recent `exploreKey`, and this needs to be handled in the code:
In `api-embed-bookmarks/index.html`, we added an event listener to store the most recent `exploreKey`:
```code
-window.addEventListener("message", (event) => {
- if (event.data?.type === "workbook:exploreKey:available") {
- latestExploreKey = event.data.exploreKey;
- if (DEBUG) console.log("Received exploreKey:", latestExploreKey);
+if (
+ data.type === "exploreCreated" ||
+ data.type === "workbook:exploreKey:onchange"
+) {
+ if (data.exploreKey) {
+ latestExploreKey = data.exploreKey;
+ if (DEBUG) {
+ console.log("Captured exploreKey:", latestExploreKey);
+ console.log("Current mode at exploreKey event:", currentMode);
+ }
+ toggleBookmarkControls(currentMode === "build");
}
-});
+}
```
This ensures that the latest exploreKey is always stored in the global `latestExploreKey` variable.
-Later, when the `Build` user clicks a `Save Bookmark` button, the value of `latestExploreKey` is passed into the API call:
-```code
-const response = await fetch("/api/bookmarks/create", {
- method: "POST",
- headers: { "Content-Type": "application/json" },
- body: JSON.stringify({
- workbookId,
- name: bookmarkName,
- exploreKey: latestExploreKey, // only the most recent value is sent
- }),
-});
-```
+Later, when the `Build` user clicks the `Save Bookmark` button, the value of `latestExploreKey` is passed into the API call.
-Once we have the table filtered, the `Bookmark Name` option appears in the application header and we can give it a name (Mobile Phones) and click `Create Bookmark`:
+Once we have the table filtered, we can give the bookmark a name (Mobile Phones) and click `Create Bookmark`:
-A popup will confirm the bookmark was created:
-
-
+A popup will confirm the bookmark, `Bookmark created successfully!`.
Click `Ok`.
@@ -142,78 +136,37 @@ The `Saved Bookmark` list now contains the new entry:
-NOTE: We decided to leave the "Original Workbook" selected after creating a bookmark.Another option is to set the embed to use the newly bookmarked version. Understanding the finer points of the workflow before coding will save time and improve user adoption.
+NOTE: We decided to leave the "Original Workbook" selected after creating a bookmark. Another option is to set the embed to use the newly bookmarked version. Understanding the finer points of the workflow before coding will save time and improve user adoption.
We can also select the `Mobile Phones` bookmark when using the `View` user:
-
-
-
-## Project Code
-Duration: 5
-
-This QuickStart builds on the shared project structure used in "REST API Usage 01: Getting Started" and introduces new files for handling bookmark functionality.
-
-The following files implement the logic for listing and creating bookmarks using the Sigma REST API:
-
-### Routes Folder
-**bookmarks/list.js:** Fetches all bookmarks associated with a workbook.
-
-- Endpoint: /api/bookmarks/list?workbookUrlId=...
-- Also uses `get-access-token.js` and the Sigma API endpoint `GET /v2/workbooks/{workbookId}/bookmarks`
-
-### Helpers Folder
-**create-bookmark.js:** Creates a new bookmark from a user-defined `exploreKey`. Requires `userEmail`, `workbookUrlId`, `exploreKey`, and `name`.
-- Endpoint: /api/bookmarks/create-bookmark
-
-- Also uses the Sigma API endpoint `POST /v2/workbooks/{workbookId}/bookmarks`
-
-### api-embed-bookmarks Folder
-**index.html:** Adds a dropdown menu to display saved bookmarks for the selected workbook.
-- Enables Build users to name and save a bookmark for their current exploration state.
-- Captures and stores the exploreKey using the `workbook:exploreKey:onchange` event.
-- Applies bookmarks by updating the embed URL or by posting a `workbook:exploreKey:apply` message.
-
-
-
-
-## Endpoint Operations Used
-Duration: 5
-
-The following is information about a few of the primary API endpoints used to enable the functionality demonstrated.
-
-The JWT token process has previously been detailed in the QuickStart: [Embedding 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_01_getting_started_v3/index.html?index=..%2F..index#0), so we won’t cover it again here.
+### View user
+We have designed the project so that the `View` user can access saved workbooks but cannot alter them or create new explorations or bookmarks.
-### GET /v2/workbooks/{workbookId}/bookmarks
-Retrieves all bookmarks saved for a given workbook.
-
-Used in:
-`/api/bookmarks/list` route.
-`loadBookmarks()` function in `index.html`.
-
-### POST /v2/workbooks/{workbookId}/bookmarks
-Creates a new bookmark from a user-defined exploration state.
-
-- Used in `/api/bookmarks/create-bookmark` route.
-- Triggered by the "Create Bookmark" button in `index.html`
-
-Requires:
-- name: Label for the bookmark
-- exploreKey: The current explore state from the embedded workbook
-- userEmail: Used for scoping permissions
+We do this by first disabling the workbook menus in the `.env` file when the `View` user is selected:
+```code
+HIDE_FOLDER_NAVIGATION=false
+HIDE_MENU=false
+MENU_POSITION=none
+```
-Returns: Metadata about the created bookmark
+In the `index.html` page we have a `toggleBookmarkControls` function that enforces:
-### isShared Parameter – What It Means
-When creating a bookmark via the Sigma API `POST /v2/workbooks/{workbookId}/bookmarks`, you can include the optional `isShared` flag:
+- For Build Users: currentMode === "build" returns true → bookmark controls shown
+- For View Users: currentMode === "build" returns false → bookmark controls hidden
+- UI Effects:
+ - Hides entire bookmark controls div (display: none)
+ - Disables create button (disabled = true)
+ - Clears bookmark name input
-- **true:** The bookmark is shared and visible to all users who have access to the workbook.
-- **false:** The bookmark is private and only visible to the user who created it.
+This ensures `View Users` cannot see or interact with bookmark creation controls, even if they somehow interact with the embedded content.
-In this QuickStart, we default to private bookmarks although `View` users were able to access the bookmark list in this design. We’ll explore another shared bookmarks design and additional collaboration patterns in the next QuickStart.
+
+IMPORTANT: We will rely on the information in the README for the implementation details and not discuss them in this QuickStart. A button is provided on the webpage for easy access.
+

@@ -223,26 +176,25 @@ Duration: 5
After creating several bookmarks for testing you may want to delete them when done. This can be done in Sigma's [API Reference](https://help.sigmacomputing.com/reference/get-started-sigma-api), but that is one at a time.
-To automate this, we created a script that will:
-
- - Accept the short workbookUrlId as a CLI argument
- - Resolve it to the full UUID
- - Fetch all bookmarks
- - Delete them one-by-one
- - Handle errors and shows progress
+To automate this, we created a script under a page button.
-IMPORTANT: Be very careful as this will permanently delete all bookmarks for the specified workbook. Use at your own risk against a production instance of Sigma.
+IMPORTANT: Be very careful as this will permanently delete all bookmarks for the specified workbook. Use at your own risk if using against a production instance of Sigma.
-Open terminal and run the following command, replacing {TARGET workbookID} with your actual workbook ID:
-```code
-node ./public/tools/delete-all-bookmarks.js {TARGET workbookID}
-```
+Select the `Build` user and a workbook to target.
+
+`Clear All Bookmarks` calls the script for you. The fetch called is `api\route\bookmarks\clear-all`.
-The output will list the bookmarks that were deleted:
+
-
+The console log will list the bookmarks that were deleted:
+```code
+Fetching bookmarks from Sigma API: https://aws-api.sigmacomputing.com/v2/workbooks/0e51172a-a4c0-4954-8c8c-9d854dcf4434/bookmarks
+Found 1 bookmarks in Sigma to delete
+✅ Deleted Sigma bookmark: Mobile Phones (879c3131-eee6-4263-8df1-4e1a4be7178a)
+✅ Clear all bookmarks completed - deleted 1 bookmarks
+```

@@ -257,6 +209,7 @@ In this QuickStart, we demonstrated how to extend your Sigma embedding experienc
- Listing all existing bookmarks for a selected workbook.
- Applying a saved bookmark using outbound `postMessage` events to update the embed in real time.
- Restricting bookmark functionality to Build users only, while still allowing View users to apply saved bookmarks.
+- Bulk deletion of bookmarks for a selected workbook.
This QuickStart builds on the foundational setup from the previous one and introduces a practical use case for interactive, personalized embedding with the Sigma API.
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/1.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/1.png
new file mode 100644
index 00000000..726cde47
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/1.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/10.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/10.png
new file mode 100644
index 00000000..a88d5d8b
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/10.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/2.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/2.png
new file mode 100644
index 00000000..7087109c
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/2.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/3.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/3.png
new file mode 100644
index 00000000..aae562bf
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/3.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/4.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/4.png
new file mode 100644
index 00000000..85d1e24d
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/4.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/5.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/5.png
new file mode 100644
index 00000000..ce0d7728
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/5.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/6.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/6.png
new file mode 100644
index 00000000..b7b3cd01
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/6.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/7.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/7.png
new file mode 100644
index 00000000..b053ded8
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/7.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/8.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/8.png
new file mode 100644
index 00000000..3cf0e617
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/8.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/9.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/9.png
new file mode 100644
index 00000000..3aff50c3
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/9.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_01.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_01.png
new file mode 100644
index 00000000..b7609bd8
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_01.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_02.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_02.png
new file mode 100644
index 00000000..66de4334
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_02.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_03.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_03.png
new file mode 100644
index 00000000..cae960d4
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_03.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_04.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_04.png
new file mode 100644
index 00000000..a572c7a8
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_04.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_05.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_05.png
new file mode 100644
index 00000000..5c19cb5d
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_05.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_06.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_06.png
new file mode 100644
index 00000000..9c87028d
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_06.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_07.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_07.png
new file mode 100644
index 00000000..e46ca839
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_07.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08.png
new file mode 100644
index 00000000..19a1f79c
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08a.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08a.png
new file mode 100644
index 00000000..e50e9774
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_08a.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09.png
new file mode 100644
index 00000000..b66e7f2d
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09a.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09a.png
new file mode 100644
index 00000000..5363ca48
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_09a.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_10.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_10.png
new file mode 100644
index 00000000..d0eccb32
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_10.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_11.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_11.png
new file mode 100644
index 00000000..be79ba96
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_11.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_12.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_12.png
new file mode 100644
index 00000000..e7ddb2cf
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_12.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_13.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_13.png
new file mode 100644
index 00000000..a89e4f1c
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_13.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_14.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_14.png
new file mode 100644
index 00000000..aa569e62
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/api_bm_14.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_01.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_01.png
new file mode 100644
index 00000000..9827c651
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_01.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_02.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_02.png
new file mode 100644
index 00000000..ead0aabc
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/bmdb_02.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/caret.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/caret.png
new file mode 100644
index 00000000..13a132ab
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/caret.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/closeview.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/closeview.png
new file mode 100644
index 00000000..d0fbb0e4
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/closeview.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/crane.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/crane.png
new file mode 100644
index 00000000..225ecf3f
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/crane.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/facebook.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/facebook.png
new file mode 100644
index 00000000..fa3f0e02
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/facebook.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/greencheckbox.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/greencheckbox.png
new file mode 100644
index 00000000..69cb876e
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/greencheckbox.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/heart_icon.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/heart_icon.png
new file mode 100644
index 00000000..bff9ea90
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/heart_icon.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/horizonalline.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/horizonalline.png
new file mode 100644
index 00000000..7c49d872
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/horizonalline.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/linkedin.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/linkedin.png
new file mode 100644
index 00000000..d1a0636d
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/linkedin.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/sigma_footer.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/sigma_footer.png
new file mode 100644
index 00000000..df51d771
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/sigma_footer.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/twitter.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/twitter.png
new file mode 100644
index 00000000..5a827d72
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/twitter.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/workflow.png b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/workflow.png
new file mode 100644
index 00000000..30d13f15
Binary files /dev/null and b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/assets/workflow.png differ
diff --git a/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db.md b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db.md
new file mode 100644
index 00000000..acaf3a77
--- /dev/null
+++ b/site/sigmaguides/src/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db/embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db.md
@@ -0,0 +1,351 @@
+author: pballai
+id: embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db
+summary: embedding_rest_api_usage_03_bookmark_sharing_with_a_local_db
+categories: embedding
+environments: web
+status: published
+feedback link: https://github.com/sigmacomputing/sigmaquickstarts/issues
+tags: default
+lastUpdated: 2025-07-01
+
+# REST API Usage 03: Bookmark Sharing with a Local DB
+
+## Overview
+Duration: 5
+
+This QuickStart demonstrates how to extend an embedded Sigma workbook with bookmark functionality using the Sigma REST API.
+
+In the previous bookmarks QuickStart, `Build` users created bookmarks, and `View` users could select and apply saved bookmarks via a dropdown in the host application.
+
+We will extend/replace that functionality to provide `Build` users a way to tightly control bookmark sharing. We won't cover every possibility, but we will cover these three:
+
+**1: Save a bookmark:**
+Allow `Build` users to save a bookmark and also select from users or teams to share the bookmark with. It is this extra detail that requires the local db, but we also need to instruct Sigma (via the API) to create a bookmark too.
+
+**2: Delete a bookmark:**
+Delete from the local db and Sigma API instead of just Sigma.
+
+**3: Manage bookmarks:**
+Allow the sharing assignments for bookmarks (selected from a list control) to be adjusted after they are created.
+
+This approach enables a more personalized sharing experience using bookmarks. It’s especially useful for SaaS providers or internal teams who want to give users the ability to revisit saved views or share context across roles — without requiring access to the full Sigma interface.
+
+This simplified workflow diagram illustrates how `Build` and `View` interact with a host application to manage and access Sigma bookmarks:
+
+
+
+
+IMPORTANT: This QuickStart builds on the setup from "REST API Usage 01: Getting Started". If you haven’t yet cloned the repo, installed dependencies, and configured your Sigma workspace, please follow that QuickStart first.
+
+
+[REST API Usage 01: Getting Started](https://quickstarts.sigmacomputing.com/guide/embedding_rest_api_usage_01_getting_started)
+
+
+IMPORTANT: Some screens in Sigma may appear slightly different from those shown here. This is because Sigma continuously adds and enhances functionality. Rest assured—Sigma’s intuitive interface ensures that any differences won’t prevent you from completing the QuickStart successfully.
+
+
+For more information on Sigma's product release strategy, see [Sigma product releases](https://help.sigmacomputing.com/docs/sigma-product-releases)
+
+If something doesn’t work as expected, here's how to [contact Sigma support](https://help.sigmacomputing.com/docs/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.
+
+
+
+IMPORTANT: Sigma recommends using non-production resources when completing QuickStarts.
+
+
+[Sigma Free Trial](https://www.sigmacomputing.com/free-trial/)
+
+[Download Visual Studio Code](https://code.visualstudio.com/download)
+
+
+IMPORTANT: Some features may carry a "Beta" tag. Beta features are subject to quick, iterative changes. As a result, the latest product version may differ from the contents of this document.
+
+
+
+
+## API Embed Bookmarks
+Duration: 5
+
+### Setup Local Database
+If you haven't already, open the project in VSCode and start a terminal session and open 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 bookmark information. We will use a version of [lowdb](https://www.npmjs.com/package/lowdb) that supports commonJS for this.
+
+
+ABOUT lowdb: lowdb is a small, fast, and zero-dependency local JSON database. It stores data in a plain .json file and provides a simple JavaScript API for reading and writing. It’s ideal for lightweight use cases like demos, prototypes, and local development — perfect for this QuickStart, where we want to persist bookmark metadata without setting up a full database server.
+
+
+Run the following command in terminal:
+```code
+npm install lowdb@1.0.0
+```
+
+Lowdb installs really quickly:
+
+
+
+The git repository already contains a `Data` folder with the required `bookmarks.json` file. The data file is initially empty except for:
+```code
+{
+ "bookmarks": []
+}
+```
+
+### Database schema
+The system maintains the local lowdb database in the `bookmarks.json` file storing:
+
+```json
+{
+ "id": "sigma-bookmark-id",
+ "userEmail": "creator@example.com",
+ "workbookUrlId": "workbook-identifier",
+ "exploreKey": "captured-state",
+ "name": "Bookmark Name",
+ "descr": "Description",
+ "isShared": true/false,
+ "sharedWith": ["email1@example.com", "team:Embed_Users"]
+}
+```
+
+Sigma acts as the source of truth for bookmarks using the following parameters:
+```code
+bookmarkId
+name
+exploreKey
+isShared
+isDefault
+```
+
+
+NOTE: In this QuickStart, we hardcode the list of users and teams for simplicity. In a production environment, these could be dynamically retrieved using the Sigma API endpoints /v2/members and /v2/teams.
+
+
+
+IMPORTANT: We will rely on the information in the README for the implementation details and not discuss them in this QuickStart. A button is provided on the webpage for easy access.
+
+
+### Start the server
+Start the Express server in terminal from the `embedding_qs_series_2_api_use_cases` folder and enable debugging:
+```code
+DEBUG=true npm start
+```
+
+The server is ready when it displays: `Server listening at http://localhost:3000`.
+
+Browse to the landing page:
+```code
+http://localhost:3000
+```
+
+Select the `API Embed Bookmarks` page and click `Go`:
+
+
+
+Select the `View` user and the `Embed_API_QuickStart` workbook.
+
+The embed loads but there are no bookmarks in the `Saved Bookmark` list yet. The `View` user has no way to create bookmarks or explore the data further as expected:
+
+
+
+
+
+
+## Create a bookmark
+Duration: 5
+
+Let's say the `View` user has requested for the workbook only to show data for mobile phones. With this embed configuration, the `Build` user can provide that by creating a bookmark.
+
+Switching to the `Build` user, we can set a filter on the table to display only rows with `Product Type` that are `Mobiles`:
+
+
+
+A few things happen when we start to interact with the table, in this case selecting a column to filter on (Product Type) and then selecting a value (Mobiles).
+
+In web browser inspection we can see that each time, a different `exploreKey` event was emitted from Sigma. This is an important observation as we only really want to create a bookmark on the most recent `exploreKey` and this needs to be handled in the code:
+
+
+
+In `api-embed-bookmarks/index.html`, we added an event listener to store the most recent `exploreKey`:
+```code
+window.addEventListener("message", (event) => {
+ if (event.data?.type === "workbook:exploreKey:available") {
+ latestExploreKey = event.data.exploreKey;
+ if (DEBUG) console.log("Received exploreKey:", latestExploreKey);
+ }
+});
+```
+
+This ensures that the latest exploreKey is always stored in the global `latestExploreKey` variable.
+
+Later, when the `Build` user clicks a `Save Bookmark` button, the value of `latestExploreKey` is passed into the API call:
+```code
+const response = await fetch("/api/bookmarks/create", {
+ method: "POST",
+ headers: { "Content-Type": "application/json" },
+ body: JSON.stringify({
+ workbookId,
+ name: bookmarkName,
+ exploreKey: latestExploreKey, // only the most recent value is sent
+ }),
+});
+```
+
+As soon as an `exploreKey` is detected, the `Manage Bookmarks` button is enabled in the host application header and we can click it to open the sidebar form. Give the bookmark the name `Mobile Phones`, and assign it to the `View User` and click `Create New`:
+
+
+
+A popup will confirm the bookmark was created with `Bookmark saved`.
+
+Click `Ok`.
+
+The `Saved Bookmark` list now contains the new entry:
+
+
+
+
+NOTE: We decided to leave the "Original Workbook" selected after creating a bookmark. Another option is to set the embed to use the newly bookmarked version. Understanding the finer points of the workflow before coding will save time and improve user adoption.
+
+
+### Delete a bookmark
+If we select the `Mobile Phones` bookmark and click `Manage Bookmarks` the sidebar panel now shows a delete button, but don't delete it just yet.
+
+
+
+
+
+
+## Testing Bookmark Visibility
+Duration: 5
+
+We can also select the `Mobile Phones` bookmark when using the `View` user, but the view user is restricted to `View` permissions and the workbook menus are not displayed:
+
+
+
+The project is configured so that the `View` user can access saved workbooks but cannot alter them or create new explorations or bookmarks.
+
+The code that restricts the view user from seeing the manage button is in the `updateBookmarkButtonState()` function in `public/api-embed-bookmarks_db/index.html`.
+
+Specifically, the code that hides the manage button for view users is:
+
+- Line 535: bookmarkToggle.style.display = "none";
+
+This line sets the `Manage Bookmarks` button's display to `none` when the current user email matches the `VIEW_EMAIL`
+from the environment configuration.
+
+This ensures `View Users` cannot see or interact with bookmark creation controls, even if they somehow interact with the embedded content.
+
+
+IMPORTANT: We will rely on the information in the README for the implementation details and not discuss them in this QuickStart. A button is provided on the webpage for easy access.
+
+
+### Create more bookmarks
+Switch back to the `Build` user.
+
+Let's create some more bookmarks, but this time, share one with the `Embed Users Team` and don't select anyone to share the third bookmark with. Select different filter values so that you can see only the data expected for each new bookmark.
+
+Once created, we will have three bookmarks in the local database, each with different share settings:
+
+
+
+Now we can check that the `View` user can see only two; the `Motorola Products` bookmark was not shared with them:
+
+
+
+This is just a simple demonstration, but now that we understand the underpinnings, other workflows are possible. For example, we could fetch all the users from some other system and populate a list or checkbox control in the manage panel to allow one or many users to be selected.
+
+With this design, it is possible to create a "bookmark library" that could be used to share many different designs of the same workbook!
+
+### Bookmarks = Custom Views in Sigma
+If we check the Sigma UI, we can see that there is an option to access `Custom View` > `All Views`:
+
+
+
+It is here that we see the result of our bookmarks in the Sigma UI. We can also see what was changed in each bookmark:
+
+
+
+
+IMPORTANT: We showed custom views in Sigma for clarity but when using this design, we have elected to not use the Sigma UI to create and manage these as we require the local database information to extend the functionality.
+
+If you delete a saved view in Sigma, it also needs to be deleted from the local database to ensure operation.
+
+
+
+
+
+## Bookmark Cleanup
+Duration: 5
+
+After creating several bookmarks for testing, you may want to delete them when done. This can be done in Sigma's [API Reference](https://help.sigmacomputing.com/reference/get-started-sigma-api), but that is one at a time.
+
+### Single delete
+If we select the `Mobile Phones` bookmark, open the manage form and click `Delete Bookmark`, it will be deleted from the local database and Sigma and we will return to the `Original Workbook`.
+
+### Bulk delete
+To automate this further, we created a script under the page button labeled `Clear All Bookmarks`.
+
+
+IMPORTANT: Be very careful as this will permanently delete all bookmarks for the specified workbook. Use at your own risk if using against a production instance of Sigma.
+
+
+Select the `Build` user and a workbook to target.
+
+`Clear All Bookmarks` calls the script for you. The fetch called is `api\route\bookmarks\clear-all`.
+
+The console log will list the bookmarks that were deleted:
+```code
+Reusing cached bearer token
+✅ Bearer token obtained for clear all operation
+Fetching bookmarks from Sigma API: https://aws-api.sigmacomputing.com/v2/workbooks/0e51172a-a4c0-4954-8c8c-9d854dcf4434/bookmarks
+Found 3 bookmarks in Sigma to delete
+✅ Deleted Sigma bookmark: Motorola Products (44a6f434-103e-40f7-bbc7-122089b73a38)
+✅ Deleted Sigma bookmark: Apple Products (c9b16a2e-92c6-486c-9029-8b30ca0d1ee7)
+✅ Deleted Sigma bookmark: Mobile Phones (9b8037f4-4900-4c58-adb9-043fd8696a87)
+✅ Deleted 3 bookmarks from local database
+✅ Total bookmarks deleted: 3 from Sigma, 3 from local DB
+```
+
+
+
+
+## What we've covered
+Duration: 5
+
+In this QuickStart, we demonstrated how to extend your Sigma embedding experience with bookmark creation and application. Specifically, we covered:
+
+- Detecting user-generated exploration states (`exploreKey`) from the embedded Sigma workbook.
+- Creating new bookmarks via the Sigma API using the current `exploreKey`.
+- Listing all existing bookmarks for a selected workbook.
+- Applying a saved bookmark using outbound `postMessage` events to update the embed in real time.
+- Restricting bookmark functionality to Build users only, while still allowing View users to apply saved bookmarks.
+
+This QuickStart builds on the foundational setup from the previous one and introduces a practical use case for interactive, personalized embedding with the Sigma API.
+
+**Additional Resource Links**
+
+[Blog](https://www.sigmacomputing.com/blog/)
+[Community](https://community.sigmacomputing.com/)
+[Help Center](https://help.sigmacomputing.com/hc/en-us)
+[QuickStarts](https://quickstarts.sigmacomputing.com/)
+
+Be sure to check out all the latest developments at [Sigma's First Friday Feature page!](https://quickstarts.sigmacomputing.com/firstfridayfeatures/)
+
+
+[ ](https://twitter.com/sigmacomputing)
+[ ](https://www.linkedin.com/company/sigmacomputing)
+[ ](https://www.facebook.com/sigmacomputing)
+
+
+
+