Skip to navigation
Sigma REST APIWorkbooks{workbookId}

Get a workbook

View as Markdown

This endpoint retrieves a workbook by its unique identifier (workbookId). It provides detailed information about the workbook, including its name, URL, path, and other metadata. You can use this endpoint to fetch specific workbook details for display or further processing within client applications.

Usage notes

  • The workbookId parameter must be a valid UUID that uniquely identifies the workbook. Invalid or nonexistent IDs return an error. Retrieve the workbookId by calling the /v2/workbooks endpoint.

Usage scenarios

  • Data retrieval: Developers can use this endpoint to programmatically retrieve details about a specific workbook to display its content or metadata in a custom user interface.
  • Integration: This endpoint is crucial for integrations where other systems need to fetch workbook details based on an ID provided through another interface or workflow.

Best practices

  • Validate the workbookId on the client side before making a request to avoid unnecessary server load caused by invalid requests.

Get the code representation of a workbook (Beta)

Beta: This documentation describes a public beta feature and is subject to the Beta features disclaimer.

You can use this endpoint to retrieve the code representation of a workbook. This representation of the workbook contents can be stored, modified, and used with the /v2/workbooks endpoint to create a new workbook with the contents defined in the representation.

To receive a code representation in the response, set the includeContents query parameter to true. For more information, see Manage workbooks as code.

Usage notes for the code representation of a workbook

  • The default response format is JSON. To use YAML, add the header Accept: application/yaml.
  • To create a new workbook from code, use POST /workbooks with contents in the request body.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

workbookIdstringRequired
Unique identifier of the workbook.

Query parameters

includeTaggedSourceUrlIdbooleanOptional

When true, returns a URL to the source document for any version-tagged workbook deployed to a tenant organization.

includeContentsbooleanOptional

Whether to include the workbook’s code representation (contents, documentVersion) in the response. Defaults to false.

Beta: This documentation describes a public beta feature and is subject to the Beta features disclaimer.

documentVersionintegerOptional

The document version to fetch. Applies only when includeContents=true. (Beta)

formatenumOptional

The response format. Defaults to json. (Beta)

Response

The response body.
workbookIdstring
Unique identifier of the workbook.
workbookUrlIdstring
namestring
urlstring
pathstring
latestVersiondouble
The most recently published document version of the workbook.
ownerIdstring
createdBystring
The identifier of the user who created this object.
updatedBystring
The identifier of the user or process that last updated this object.
createdAtdatetime
When the object was created.
updatedAtdatetime
When the object was last updated.
isArchivedbooleanOptional
tagslist of objectsOptional
descriptionstringOptional
taggedSourceUrlIdstringOptional

For a workbook deployed to a tenant organization by a deployment policy with a version tag, the urlId of the original source workbook in the parent organization. Only present when includeTaggedSourceUrlId=true is included in the request.

documentVersiondoubleOptional

The document version of the workbook. Only present when includeContents=true is included in the request. (Beta)

contentsobjectOptional

The code representation of the workbook: its pages, elements, columns, sources, layout, and theme. Only present when includeContents=true is included in the request. To reproduce this workbook, submit this object as the contents field of a create or update request. Everything outside contents is workbook metadata that Sigma maintains, and is ignored when you write. (Beta)