Update a workbook from a code representation (Beta)

This endpoint replaces a workbook with a workbook defined in a code representation. You can programmatically update the workbook’s structure, metadata, and contents. This creates a new version of the workbook, which is accessible from the Sigma UI.

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

System and user requirements

• To perform this operation, you must use API credentials owned by a user assigned an account type with Create, edit, and publish workbooks permission.
• To perform this operation, you must use API credentials owned by a user with Can edit access for the workbook.

Usage notes

• The default response format is JSON. To use YAML, add the header Accept: application/yaml.
• You can define the layout of contents on the workbook page using XML in the contents.layout field. Grid containers use gridColumn and gridRow; stack containers use ordered children plus optional nested <Style><Desktop .../><Mobile .../></Style> and per-child <Size><Desktop .../><Mobile .../></Size> settings. For more information, see Customize the layout of a workbook in code representation.
• You can combine multiple YAML documents to create one workbook representation. For more information, see Prepare a representation from multiple YAML documents.
• To retrieve the current representation of a workbook, use GET /workbooks/{workbookId}?includeContents=true.
• To create a new workbook from code, use POST /workbooks with contents in the request body.
• When documentVersion is provided in the request body, the update fails when the workbook has changed since that version. If omitted, the update preserves last-write-wins behavior.
• The endpoint only supports updates to the contents object. Workbook metadata sent alongside contents — including name, folderId, and description — is ignored, so you can submit a GET response unchanged. To rename or move a workbook, use the /v2/files/{fileId} endpoint.
• Partial updates are not supported. You must provide the entire representation of the workbook in the request body.

Usage scenarios

• Agentic workflows: Agents can use these endpoints to directly manage workbook contents in code.
• Automation: If you want to update several workbooks across one or more organizations, or in response to external events, you can use this endpoint to programmatically update the workbooks.
• Integration: Using this endpoint, you can update workbooks based on external data sources or integrate Sigma with other tools and platforms.