Create an embed for a workbook
This endpoint lets you create an embed for a specific workbook. You can embed an entire workbook, a specific page, or an individual element within a workbook. Embedding enables seamless integration of Sigma content into other applications, websites, or internal platforms, providing a flexible and dynamic way to present and interact with data.
Embedding options
-
Publicly embed Sigma in a public website by creating an embed of type
public. -
Securely embed Sigma in an authenticated host application.
- (Recommended) Use JSON Web Tokens (JWT) to sign the workbook URL outputted by the /v2/workbooks endpoint instead of the output of this endpoint. See Create a secure embed.
- (Deprecated) Use this endpoint to create an embed of type
secure. This option is deprecated. See Migrate to JWT-signed secure embed URLs.
Usage notes
-
The endpoint requires the workbookId as a path parameter. Retrieve the workbookId by calling the /v2/workbooks endpoint.
-
The body of the request must specify the type of embed (public).
-
You must specify the source type (workbook, page, element) and ID for that source to create the embed.
- Retrieve the pageId by calling the /v2/workbooks/{workbookId}/pages endpoint.
- Retrieve the elementId by first calling the /v2/workbooks/{workbookId}/pages endpoint, then calling the /v2/workbooks/{workbookId}/pages/{pageId}/elements endpoint.
Usage scenarios
- Web application integration: Developers can use this API to generate the embed URL for integration into their application or for display on a public-facing webpage.
Best practices
- Validate the
workbookIdandsourceIdto ensure they refer to existing resources before attempting to create an embed. - Consider the security settings of the embed type to match the integration context, ensuring that data exposure is controlled and appropriate for the audience.
Authentication
OAuth authentication of the form <token>.
Path parameters
Request
Defines the visibility and access control of the embed. Choose public for open access.
Specifies the scope of the embed: “workbook” for the entire workbook, “page” for a single page, or “element” for a specific element within the workbook.