> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Update a workbook from a code representation (Beta)

PUT https://api.sigmacomputing.com/v2/workbooks/{workbookId}/contents
Content-Type: application/json

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](/docs/sigma-product-releases#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. For more information, see [Customize the layout of a workbook in code representation](https://help.sigmacomputing.com/docs/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](https://help.sigmacomputing.com/docs/create-a-workbook-from-a-code-representation#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}](https://help.sigmacomputing.com/reference/updatefile) 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.

Reference: https://help.sigmacomputing.com/reference/update-workbook-contents

## Authentication

- OAuth2 — send the obtained token as `Authorization: Bearer <token>`

## Servers

- `https://api.sigmacomputing.com` (Server for GCP (US) hosted organizations, default)
- `https://api.sa.gcp.sigmacomputing.com` (Server for GCP (KSA) hosted organizations)
- `https://aws-api.sigmacomputing.com` (Server for AWS US (West) hosted organizations)
- `https://api.us-a.aws.sigmacomputing.com` (Server for AWS US (East) hosted organizations)
- `https://api.ca.aws.sigmacomputing.com` (Server for AWS Canada hosted organizations)
- `https://api.eu.aws.sigmacomputing.com` (Server for AWS Europe hosted organizations)
- `https://api.au.aws.sigmacomputing.com` (Server for AWS Australia and APAC hosted organizations)
- `https://api.uk.aws.sigmacomputing.com` (Server for AWS UK hosted organizations)
- `https://api.us.azure.sigmacomputing.com` (Server for Azure US hosted organizations)
- `https://api.eu.azure.sigmacomputing.com` (Server for Azure Europe hosted organizations)
- `https://api.ca.azure.sigmacomputing.com` (Server for Azure Canada hosted organizations)
- `https://api.uk.azure.sigmacomputing.com` (Server for Azure United Kingdom hosted organizations)
- `https://api.au.azure.sigmacomputing.com` (Server for Azure Australia hosted organizations)

## Request

### Path parameters

- `workbookId` (string, required) — Unique identifier of the workbook.

### Body (application/json)

This endpoint expects an object.

- `contents` (object, required) — The code representation of the workbook to write: its pages, elements, columns, sources, layout, and theme.
  - `schemaVersion` (enum, required) — The schema version used by this representation of the workbook.
    - Allowed values: `1`
  - `kind` (enum, required) — Document kind. Always `workbook` for this resource.
    - Allowed values: `workbook`
  - `pages` (list of object, required) — The pages of the workbook.
    - `id` (string, required) — The identifier of the page in the workbook.
    - `name` (string, required) — The name of the page.
    - `type` (enum, optional) — The page type, distinguishing a regular page from a `modal`, `drawer`, or `popover`. Only `page` can be set. If omitted, `page` is assumed.
      - Allowed values: `page`
    - `visibility` (enum or object, optional) — The visibility settings for the page. If omitted, the page is visible to all users. Specify `hidden` to hide the page, or define `{ kind: 'specific-users-and-teams', assignments: { users: [...], teams: [...] } }` to limit visibility to particular users and teams.
      - object
        - `kind` (enum, required)
          - Allowed values: `specific-users-and-teams`
        - `assignments` (object, required) — The identifiers of the users and teams allowed to view this page.
          - `users` (list of string, optional) — The identifiers of the users allowed to view this page.
          - `teams` (list of string, optional) — The identifiers of the teams allowed to view this page.
    - `backgroundImage` (object, optional) — The page background image. The URL supports dynamic `{{formula}}` text.
      - `source` (object or object, required) — The image source. Either an external URL (supports dynamic `{{formula}}` text) or an image uploaded into Sigma.
        - External URL
          - `kind` (enum, required)
            - Allowed values: `url`
          - `url` (string, required) — The external image URL. Supports dynamic `{{formula}}` text.
        - Uploaded Image
          - `kind` (enum, required)
            - Allowed values: `upload`
          - `key` (string, required) — The identifier for an image uploaded to Sigma.
      - `style` (object, optional) — The image sizing and alignment within the element.
        - `fit` (enum or enum or enum or enum or enum, optional) — How the image fits the container.
        - `horizontalAlign` (enum or enum or enum, optional) — The horizontal alignment of the image within its container.
        - `verticalAlign` (enum or enum or enum, optional) — The vertical alignment of the image within its container.
        - `tiling` (enum or enum, optional) — The tiling behavior for the image. `none` displays a single image (default). `repeat` tiles the image to fill the container.
    - `backgroundColor` (string or string or object, optional) — The page background color. A hex code, `rgb()` value, or theme reference.
      - object
        - `kind` (enum, required)
          - Allowed values: `theme`
        - `ref` (string, required)
    - `pageWidth` (enum or enum or enum or object, optional) — The width of the page. One of `full`, `large`, `medium`, or `{ mode: 'custom', maxWidth }` for a fixed pixel width.
      - object
        - `mode` (enum, required)
          - Allowed values: `custom`
        - `maxWidth` (double, required) — The fixed page width in pixels, when `mode` is `custom`.
  - `elements` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The elements in this workbook and their definitions.
    - Chat
      - `id` (string, required) — The identifier of the chat element.
      - `kind` (enum, required)
        - Allowed values: `chat`
      - `agentId` (string, optional) — The identifier of the workbook agent, declared in `agents`, connected to this chat element. Omit when the chat has no agent, or when its agent is not a workbook agent.
    - Code
      - `id` (string, required) — The identifier of the code element.
      - `kind` (enum, required)
        - Allowed values: `code`
      - `code` (string, optional) — Python code the element runs, as written in the code editor. Empty until code is saved.
      - `connectionId` (string, optional) — Identifier of the connection the code runs on. Absent when the element has no connection yet.
    - Container
      - `id` (string, required) — The identifier of the container.
      - `kind` (enum, required)
        - Allowed values: `container`
      - `conditionalFormats` (list of object, optional) — Conditional formatting rules, evaluated in order. The first matching rule determines the container's background color.
        - `id` (string, required)
        - `formula` (string, required) — Boolean formula.
        - `config` (object, required)
          - `backgroundColor` (string or string or object, required) — Background color.
            - object
      - `style` (object or object, optional) — The visual styling, including background color, border, corner shape, and padding.
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `backgroundImage` (object, optional) — The background image of the container. The URL supports dynamic `{{formula}}` text.
        - `source` (object or object, required) — The image source. Either an external URL (supports dynamic `{{formula}}` text) or an image uploaded into Sigma.
          - External URL
            - `kind` (enum, required)
            - `url` (string, required) — The external image URL. Supports dynamic `{{formula}}` text.
          - Uploaded Image
            - `kind` (enum, required)
            - `key` (string, required) — The identifier for an image uploaded to Sigma.
        - `style` (object, optional) — The image sizing and alignment within the element.
          - `fit` (enum or enum or enum or enum or enum, optional) — How the image fits the container.
          - `horizontalAlign` (enum or enum or enum, optional) — The horizontal alignment of the image within its container.
          - `verticalAlign` (enum or enum or enum, optional) — The vertical alignment of the image within its container.
          - `tiling` (enum or enum, optional) — The tiling behavior for the image. `none` displays a single image (default). `repeat` tiles the image to fill the container.
      - `spacing` (enum or enum or enum, optional) — The element spacing preset.
      - `elementGap` (enum or enum, optional) — The gap between child elements. Defaults to `shown`.
    - Form
      - `id` (string, required) — The identifier of the form.
      - `kind` (enum, required)
        - Allowed values: `form`
      - `fields` (list of object or object or object, required) — The form fields, in display order.
        - Simple field
          - `fieldId` (string, required) — The identifier used to reference this field in formulas and actions.
          - `type` (enum or enum or enum or enum or enum, required) — A text, number, date, or checkbox input.
          - `label` (string, optional) — The label shown for the field.
          - `placeholder` (string, optional) — Placeholder text shown while the field is empty.
          - `validation` (object or object or object or object, optional) — The validation rule for the field.
            - Number range
            - Date range
            - Text match
            - File
          - `hintText` (string, optional) — Hint text shown beneath the field.
          - `rules` (object, optional) — Rules that apply to the field.
            - `readOnly` (enum, optional) — Set to `read-only` to prevent editing the field.
            - `requiredInput` (enum, optional) — Set to `required` when the field must be filled before the form is submitted.
          - `defaultValue` (object or object, optional) — The field default value.
            - object
            - object
          - `format` (object or object, optional) — The number display format. Only applies to number fields.
            - object
            - object
        - File upload field
          - `fieldId` (string, required) — The identifier used to reference this field in formulas and actions.
          - `type` (enum, required) — A file-upload input.
            - Allowed values: `file-upload`
          - `label` (string, optional) — The label shown for the field.
          - `placeholder` (string, optional) — Placeholder text shown while the field is empty.
          - `validation` (object or object or object or object, optional) — The validation rule for the field.
            - Number range
            - Date range
            - Text match
            - File
          - `hintText` (string, optional) — Hint text shown beneath the field.
          - `rules` (object, optional) — Rules that apply to the field.
            - `requiredInput` (enum, optional) — Set to 'required' when at least one file is required before submit.
            - `fileSelection` (enum, optional) — Set to 'multiple' when the field accepts multiple files.
            - `restrictNumberOfFiles` (double, optional) — The maximum number of files allowed when `fileSelection` is `multiple`.
          - `defaultValue` (object or object, optional) — The field default value.
            - object
            - object
          - `format` (object or object, optional) — The number display format. Only applies to number fields.
            - object
            - object
        - Choice field
          - `fieldId` (string, required) — The identifier used to reference this field in formulas and actions.
          - `type` (enum or enum or enum or enum, required) — The type of choice input, such as a dropdown or a radio group.
          - `source` (object or object or object, required) — The source for options. Either a manual list or values from a column.
            - Manual
            - Source
            - Input-table column
          - `label` (string, optional) — The label shown for the field.
          - `placeholder` (string, optional) — Placeholder text shown while the field is empty.
          - `validation` (object or object or object or object, optional) — The validation rule for the field.
            - Number range
            - Date range
            - Text match
            - File
          - `hintText` (string, optional) — Hint text shown beneath the field.
          - `selection` (enum or enum, optional) — For a `dropdown` field, whether the dropdown is 'single' or 'multiple' selection.
          - `rules` (object, optional) — Rules that apply to the field.
            - `readOnly` (enum, optional) — Set to `read-only` to prevent editing the field.
            - `requiredInput` (enum, optional) — Set to `required` when the field must be filled before the form is submitted.
          - `sort` (object, optional) — How the options are ordered. Defaults to ascending alphabetical.
            - `by` (enum or enum, required) — The sort order for options. One of `value` (alphanumeric) or `count` (frequency).
            - `direction` (enum or enum, required) — The sort direction.
          - `format` (object or object, optional) — Option display format for number or date options.
            - object
            - object
          - `defaultValue` (object or object, optional) — The field default value.
            - object
            - object
      - `style` (object or object, optional) — Visual styling: background color, border, corners, padding, and field spacing.
        - object
          - `padding` (enum, required) — Set to `'none'` to drop form padding.
            - Allowed values: `none`
          - `backgroundColor` (string, optional) — Form background color (hex).
          - `corner` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `spacing` (enum or enum or enum, optional) — The element spacing preset.
          - `fieldGap` (enum or enum, optional) — Whether a gap between fields is shown. Defaults to `shown`.
        - object
          - `backgroundColor` (string, optional) — Form background color (hex).
          - `corner` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (enum or enum or enum or enum, optional) — Border width in pixels. `0` means no border.
          - `borderColor` (string or string or object, optional) — Border color (hex, rgb(), or theme reference).
            - object
          - `spacing` (enum or enum or enum, optional) — The element spacing preset.
          - `fieldGap` (enum or enum, optional) — Whether a gap between fields is shown. Defaults to `shown`.
      - `header` (object, optional) — The title and description configuration.
        - `title` (object, optional) — The form title and its styling.
          - `visibility` (enum or enum, optional) — Whether the text is shown.
          - `text` (string, optional) — The text content. Supports dynamic `{{formula}}` text.
          - `color` (string or string or object, optional) — The text color.
            - object
          - `fontSize` (double, optional) — The font size in pixels. One of `6` through `96`.
          - `fontWeight` (enum or enum, optional) — The font weight.
          - `align` (enum or enum or enum, optional) — The horizontal alignment of the title.
        - `description` (object, optional) — The form description and its styling.
          - `visibility` (enum or enum, optional) — Whether the text is shown.
          - `text` (string, optional) — The text content. Supports dynamic `{{formula}}` text.
          - `color` (string or string or object, optional) — The text color.
            - object
          - `fontSize` (double, optional) — The font size in pixels. One of `6` through `96`.
          - `fontWeight` (enum or enum, optional) — The font weight.
      - `fieldLabels` (object, optional) — The field label placement and styling.
        - `position` (enum or enum, optional) — The position of the field labels. Defaults to `top`.
        - `width` (enum or enum or enum or enum, optional) — The width of the field label as a fraction of the field row.
        - `color` (string or string or object, optional) — The label color.
          - object
            - `kind` (enum, required)
            - `ref` (string, required)
        - `fontWeight` (enum or enum, optional) — The label font weight.
      - `footer` (object, optional) — The submit, reset, and tertiary button labels, visibility, and alignment.
        - `align` (enum or enum or enum or enum, optional) — The button row alignment.
        - `primary` (object, optional) — The primary (submit) button. Defaults to "Submit".
          - `label` (string, optional) — The button label. Supports dynamic `{{formula}}` text.
          - `visibility` (enum or enum, optional) — Whether the button is shown.
        - `secondary` (object, optional) — The secondary (reset) button. Defaults to "Reset form".
          - `label` (string, optional) — The button label. Supports dynamic `{{formula}}` text.
          - `visibility` (enum or enum, optional) — Whether the button is shown.
        - `tertiary` (object, optional) — The tertiary button.
          - `label` (string, optional) — The button label. Supports dynamic `{{formula}}` text.
          - `visibility` (enum or enum, optional) — Whether the button is shown.
      - `actions` (list of object, optional) — The actions triggered by interacting with this element.
        - `id` (string, required) — The identifier of the action sequence.
        - `trigger` (enum or enum or enum or enum or enum or enum or enum or enum or object or object or object, required) — The user interaction that initiates this action, such as a button click or cell selection.
          - object
            - `on` (enum or enum or enum or enum or enum or enum or enum or enum, required)
            - `condition` (object or object or object or object or object, required)
          - object
            - `on` (enum, required)
            - `menuItemId` (string, required) — The customContextMenu item's id this trigger targets.
            - `condition` (object or object or object or object or object, optional)
          - object
            - `kind` (enum, required)
            - `actionTriggerId` (string, required) — The identifier of the action trigger that fires this action.
            - `condition` (object or object or object or object or object, optional)
        - `effects` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The effects that run when the trigger occurs.
          - If/Else
            - `effect` (enum, required)
            - `if` (object, required) — Runs when its condition is true.
            - `elseif` (list of object, optional) — Additional branches, evaluated in order if `if` does not match.
            - `else` (object, optional) — Runs when no branch condition matches.
        - `name` (string, optional) — Optional display name for the action.
        - `state` (enum or enum, optional) — Whether the action runs. Defaults to `enabled`.
        - `successToast` (object, optional) — The message shown after this action runs successfully.
          - `showMessage` (enum or enum, required) — Whether the `message` line renders below the title of the action success message.
          - `title` (string, optional) — The title of the action success message. Supports dynamic `{{formula}}` text.
          - `message` (string, optional) — The message displayed to the user when the action completes successfully.
        - `summary` (string, optional) — A description of what this action sequence does.
    - Repeated container
      - `id` (string, required) — The identifier of the repeated container.
      - `kind` (enum, required)
        - Allowed values: `repeated-container`
      - `source` (object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The data source used to generate cards in the repeated container.
        - Warehouse Table
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `warehouse-table`
        - CSV Table
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `csv-table`
          - `inodeId` (string, required) — The identifier of the table created from a CSV.
        - Metric View
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `metric-view`
        - Semantic View
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `semantic-view`
        - Custom SQL
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `sql`
          - `statement` (string, required) — The custom SQL statement used in the element.
        - Table
          - `kind` (enum, required)
            - Allowed values: `table`
          - `elementId` (string, required) — The identifier of the table in this data model.
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Data Model
          - `dataModelId` (string, required) — The identifier of the data model source.
          - `elementId` (string, required) — The identifier of the table in the referenced data model.
          - `kind` (enum, required)
            - Allowed values: `data-model`
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Code Output
          - `kind` (enum, required)
            - Allowed values: `code-output`
          - `elementId` (string, required) — The identifier of the code (Python) element whose output to display.
          - `output` (string, required) — Name of the code element's output — the sigma.output('name', …) name — to display.
        - Join
          - `kind` (enum, required)
            - Allowed values: `join`
          - `joins` (list of object, required) — A list of the joins and their definitions. The left of each join must be either the primary source or the right of some other join.
            - `left` (object or object or object or object, required) — The name of the left table in the join.
            - `right` (object or object or object or object, required) — The name of the right table in the join.
            - `columns` (list of object, required) — A list of the column pairs and operators that define this join.
            - `name` (string, optional) — The name of the join. Defaults to the name of the right.
            - `joinType` (enum or enum or enum or enum or enum, optional) — The logical join type.
          - `name` (string, optional) — The name of the join. Defaults to the name of the primary source.
          - `primarySource` (object or object or object or object, optional) — The primary/head source of the join. If not specified, it is inferred as the unique source that appears on the left of some join but never on the right.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
        - Union
          - `kind` (enum, required)
            - Allowed values: `union`
          - `sources` (list of object or object or object or object, required) — The identifiers of the sources in the union.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
          - `matches` (list of object, required) — The union output columns and the matched source columns that comprise them.
            - `outputColumnName` (string, required) — The name of the union output column.
            - `sourceColumns` (list of string, required) — The matching set of source columns that correspond to the union output column.
        - Unnest
          - `kind` (enum, required)
            - Allowed values: `unnest`
          - `source` (object or object or object or object, required) — The source containing the array column to unnest.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
          - `arrayColumn` (string, required) — The variant column containing arrays to unnest.
          - `valueColumn` (string, required) — The name of the generated column containing array values.
          - `outputColumns` (list of string, required) — The columns included in the unnest output.
          - `indexColumn` (string, optional) — The name of the generated zero-based array index column.
          - `preserveAllSourceRows` (enum or enum, optional) — Whether to preserve rows whose array column is null or empty.
      - `arrangement` (enum or enum, optional) — How cards are tiled inside the repeated container. Defaults to `grid`.
      - `style` (object or object, optional) — The styling of the element, including background, border, corner shape, and padding.
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `cardStyle` (object or object, optional) — Per-card styling: background, border, corners, padding toggle, and optional URL-only background image (uploads not supported).
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `noDataText` (string, optional) — The message shown when the data source has no rows.
      - `cardGap` (enum or enum, optional) — The gap between cards in the repeated container. Defaults to `shown`.
      - `elementGap` (enum or enum, optional) — Whether there's a gap between elements inside each card. Defaults to `shown`.
      - `cardSpacing` (enum or enum or enum, optional) — Gap/padding size between cards (pairs with cardGap). Small, medium, or large.
      - `elementSpacing` (enum or enum or enum, optional) — The gap between elements inside each card. When padding is enabled, also determines padding size.
      - `sort` (list of object, optional) — The sort order applied to the source rows behind the cards. Requires a `source` of `table`.
        - `columnId` (string, required) — The identifier of the column by which to sort.
        - `direction` (enum or enum, required) — The sort direction.
        - `nulls` (enum or enum or enum, optional) — How the sort order treats null values.
      - `filters` (list of object or object or object or object or object or object, optional) — The column filters applied to the source rows that drive the repeated container cards.
        - Number Range
          - `kind` (enum, required)
            - Allowed values: `number-range`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `includeNulls` (enum or enum or enum, optional) — When to include null values in the filter results.
          - `min` (double, optional) — The lower bound of the selected number range.
          - `max` (double, optional) — The upper bound of the selected number range.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
        - Date Range
          - `kind` (enum, required)
            - Allowed values: `date-range`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `includeNulls` (enum or enum or enum, optional) — When to include null values in the filter results.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
        - Top N
          - `kind` (enum, required)
            - Allowed values: `top-n`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
        - List
          - `kind` (enum, required)
            - Allowed values: `list`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `mode` (enum or enum, optional) — Whether the selected values are included or excluded by the filter. Defaults to `include`.
          - `values` (list of boolean or list of double or list of string or list of string, optional) — The list of selected values.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
        - Text Match
          - `kind` (enum, required)
            - Allowed values: `text-match`
          - `mode` (enum or enum or enum or enum or enum or enum or enum or enum or enum or enum or enum or enum, required) — The type of text comparison to make.
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `value` (string, optional) — The string to compare against the filter pattern.
          - `case` (enum or enum, optional) — Whether the text comparison is case sensitive.
          - `includeNulls` (enum or enum or enum, optional) — When to include null values in the filter results.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
        - Hierarchy
          - `kind` (enum, required)
            - Allowed values: `hierarchy`
          - `id` (string, required) — The identifier of the filter.
          - `columnId` (string, required) — The identifier of the column this filter targets.
          - `mode` (enum or enum, optional) — Whether the selected values are included or excluded by the filter. Defaults to `include`.
          - `values` (list of list of string, optional) — The hierarchy paths selected by the filter.
          - `state` (enum or enum, optional) — Whether the filter is enabled.
      - `scroll` (enum or enum or enum, optional) — The scroll behavior for overflowing cards. Defaults to vertical scrolling.
      - `cardSize` (enum or enum or enum or enum or enum, optional) — The preset card width for the `grid` layout type. Defaults to `medium`.
      - `conditionalFormats` (list of object, optional) — Conditional formatting rules, evaluated in order. The first matching rule determines the background color.
        - `id` (string, required)
        - `formula` (string, required) — Boolean formula.
        - `config` (object, required)
          - `backgroundColor` (string or string or object, required) — Background color.
            - object
      - `actions` (list of object, optional) — The actions triggered by interacting with this element.
        - `id` (string, required) — The identifier of the action sequence.
        - `trigger` (enum or enum or enum or enum or enum or enum or enum or enum or object or object or object, required) — The user interaction that initiates this action, such as a button click or cell selection.
          - object
            - `on` (enum or enum or enum or enum or enum or enum or enum or enum, required)
            - `condition` (object or object or object or object or object, required)
          - object
            - `on` (enum, required)
            - `menuItemId` (string, required) — The customContextMenu item's id this trigger targets.
            - `condition` (object or object or object or object or object, optional)
          - object
            - `kind` (enum, required)
            - `actionTriggerId` (string, required) — The identifier of the action trigger that fires this action.
            - `condition` (object or object or object or object or object, optional)
        - `effects` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The effects that run when the trigger occurs.
          - If/Else
            - `effect` (enum, required)
            - `if` (object, required) — Runs when its condition is true.
            - `elseif` (list of object, optional) — Additional branches, evaluated in order if `if` does not match.
            - `else` (object, optional) — Runs when no branch condition matches.
        - `name` (string, optional) — Optional display name for the action.
        - `state` (enum or enum, optional) — Whether the action runs. Defaults to `enabled`.
        - `successToast` (object, optional) — The message shown after this action runs successfully.
          - `showMessage` (enum or enum, required) — Whether the `message` line renders below the title of the action success message.
          - `title` (string, optional) — The title of the action success message. Supports dynamic `{{formula}}` text.
          - `message` (string, optional) — The message displayed to the user when the action completes successfully.
        - `summary` (string, optional) — A description of what this action sequence does.
    - Single-row container
      - `id` (string, required) — The identifier of the single-row container.
      - `kind` (enum, required)
        - Allowed values: `single-row-container`
      - `source` (object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The data source that supplies the displayed row.
        - Warehouse Table
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `warehouse-table`
        - CSV Table
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `csv-table`
          - `inodeId` (string, required) — The identifier of the table created from a CSV.
        - Metric View
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `metric-view`
        - Semantic View
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `path` (list of string, required) — The path of the object in the data platform.
          - `kind` (enum, required)
            - Allowed values: `semantic-view`
        - Custom SQL
          - `connectionId` (string, required) — The identifier of the connection to the data platform.
          - `kind` (enum, required)
            - Allowed values: `sql`
          - `statement` (string, required) — The custom SQL statement used in the element.
        - Table
          - `kind` (enum, required)
            - Allowed values: `table`
          - `elementId` (string, required) — The identifier of the table in this data model.
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Data Model
          - `dataModelId` (string, required) — The identifier of the data model source.
          - `elementId` (string, required) — The identifier of the table in the referenced data model.
          - `kind` (enum, required)
            - Allowed values: `data-model`
          - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
        - Code Output
          - `kind` (enum, required)
            - Allowed values: `code-output`
          - `elementId` (string, required) — The identifier of the code (Python) element whose output to display.
          - `output` (string, required) — Name of the code element's output — the sigma.output('name', …) name — to display.
        - Join
          - `kind` (enum, required)
            - Allowed values: `join`
          - `joins` (list of object, required) — A list of the joins and their definitions. The left of each join must be either the primary source or the right of some other join.
            - `left` (object or object or object or object, required) — The name of the left table in the join.
            - `right` (object or object or object or object, required) — The name of the right table in the join.
            - `columns` (list of object, required) — A list of the column pairs and operators that define this join.
            - `name` (string, optional) — The name of the join. Defaults to the name of the right.
            - `joinType` (enum or enum or enum or enum or enum, optional) — The logical join type.
          - `name` (string, optional) — The name of the join. Defaults to the name of the primary source.
          - `primarySource` (object or object or object or object, optional) — The primary/head source of the join. If not specified, it is inferred as the unique source that appears on the left of some join but never on the right.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
        - Union
          - `kind` (enum, required)
            - Allowed values: `union`
          - `sources` (list of object or object or object or object, required) — The identifiers of the sources in the union.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
          - `matches` (list of object, required) — The union output columns and the matched source columns that comprise them.
            - `outputColumnName` (string, required) — The name of the union output column.
            - `sourceColumns` (list of string, required) — The matching set of source columns that correspond to the union output column.
        - Unnest
          - `kind` (enum, required)
            - Allowed values: `unnest`
          - `source` (object or object or object or object, required) — The source containing the array column to unnest.
            - Warehouse Table
            - CSV Table
            - Table
            - Data Model
          - `arrayColumn` (string, required) — The variant column containing arrays to unnest.
          - `valueColumn` (string, required) — The name of the generated column containing array values.
          - `outputColumns` (list of string, required) — The columns included in the unnest output.
          - `indexColumn` (string, optional) — The name of the generated zero-based array index column.
          - `preserveAllSourceRows` (enum or enum, optional) — Whether to preserve rows whose array column is null or empty.
      - `keyColumnId` (string, required) — The ID of the source column that identifies which row is displayed. Must be a column declared on the source.
      - `keyColumnValue` (boolean or double or string or string, optional, nullable) — The key-column value of the row to display. Must match the key column type. Omit to pin no row.
      - `style` (object or object, optional) — The visual styling, including background color, border, corner shape, and padding.
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `backgroundImage` (object, optional) — The background image of the container. The URL supports dynamic `{{formula}}` text.
        - `source` (object or object, required) — The image source. Either an external URL (supports dynamic `{{formula}}` text) or an image uploaded into Sigma.
          - External URL
            - `kind` (enum, required)
            - `url` (string, required) — The external image URL. Supports dynamic `{{formula}}` text.
          - Uploaded Image
            - `kind` (enum, required)
            - `key` (string, required) — The identifier for an image uploaded to Sigma.
        - `style` (object, optional) — The image sizing and alignment within the element.
          - `fit` (enum or enum or enum or enum or enum, optional) — How the image fits the container.
          - `horizontalAlign` (enum or enum or enum, optional) — The horizontal alignment of the image within its container.
          - `verticalAlign` (enum or enum or enum, optional) — The vertical alignment of the image within its container.
          - `tiling` (enum or enum, optional) — The tiling behavior for the image. `none` displays a single image (default). `repeat` tiles the image to fill the container.
      - `spacing` (enum or enum or enum, optional) — The element spacing preset.
      - `elementGap` (enum or enum, optional) — The gap between child elements. Defaults to `shown`.
    - Tabbed container
      - `id` (string, required) — The identifier of the tabbed container.
      - `kind` (enum, required)
        - Allowed values: `tabbed-container`
      - `tabs` (list of object, required) — The ordered list of tabs in the tabbed container. Must contain at least one tab. The first tab is the default. The `layout` for each tab is matched to this list by position.
        - `name` (string, required) — The label shown on the tab.
      - `style` (object or object, optional) — The visual styling, including background color, border, corner shape, and padding.
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `spacing` (enum or enum or enum, optional) — The element spacing preset.
      - `elementGap` (enum or enum, optional) — The gap between child elements. Defaults to `shown`.
      - `tabBar` (object, optional) — The tab bar display options for the tabbed container.
        - `visibility` (enum or enum, optional) — Whether the tab bar is shown. Defaults to `shown`.
        - `style` (enum or enum or enum, optional) — The tab style. Defaults to `open`.
        - `alignment` (enum or enum or enum or enum, optional)
        - `size` (enum or enum or enum, optional) — The tab bar size. Defaults to `medium`.
    - Page break
      - `id` (string, required) — The identifier of the page break element.
      - `kind` (enum, required)
        - Allowed values: `page-break`
    - Value list
      - `id` (string, required) — The identifier of the value list element.
      - `kind` (enum, required)
        - Allowed values: `value-list`
      - `fields` (list of object, required) — The fields shown in this value list, in display order.
        - `fieldId` (string, required) — Field id used to reference this field in formulas.
        - `formula` (string, required) — Formula text for the field value.
        - `label` (string, optional) — Display label for the field.
        - `format` (object or object, optional) — Number or date display format for the field value.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The number format string in d3 format syntax. E.g., `.2s` for SI notation with two significant digits (1.2k) or `#x` for prefixed hexadecimal (0x4d3).
            - `prefix` (string, optional) — The prefix to apply to the number.
            - `suffix` (string, optional) — The suffix appended to the number. E.g., `'%'` or `'units'`.
            - `displayNullAs` (string, optional) — The display value to show for null values.
            - `decimalSymbol` (string, optional) — The character used for decimal notation.
            - `digitGroupingSymbol` (string, optional) — The character used to separate digits in large numbers.
            - `digitGroupingSize` (list of double, optional) — The number of digits between grouping symbols.
            - `currencySymbol` (string, optional) — The characters used for currency.
          - object
            - `kind` (enum, required)
            - `formatString` (string, optional) — The format of the date, specified in d3 time format.
      - `style` (object or object, optional) — The element background, border, and padding.
        - object
          - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - Allowed values: `none`
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - object
          - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - object
          - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
          - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
            - object
      - `hasGap` (enum or enum, optional) — Whether a gap is shown between fields.
      - `spacing` (enum or enum or enum, optional) — Gap/padding size between fields.
      - `fieldLayout` (object or object or object or object, optional) — Layout and text styling shared across all fields. Defaults to a grid layout.
        - object
          - `layoutType` (enum, required)
            - Allowed values: `grid`
          - `labelWidth` (enum or enum or enum, optional) — Label column width as a fraction. Defaults to 0.25.
          - `labelConfig` (object, optional) — Styling applied to every field label.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
          - `valueConfig` (object, optional) — Styling applied to every field value.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
        - object
          - `layoutType` (enum, required)
            - Allowed values: `stacked`
          - `maxColumns` (enum or enum or enum or enum or enum or enum or enum or enum, optional) — Number of columns. Defaults to 4.
          - `labelConfig` (object, optional) — Styling applied to every field label.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
          - `valueConfig` (object, optional) — Styling applied to every field value.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
        - object
          - `layoutType` (enum, required)
            - Allowed values: `compact`
          - `labelConfig` (object, optional) — Styling applied to every field label.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
          - `valueConfig` (object, optional) — Styling applied to every field value.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
        - object
          - `layoutType` (enum, required)
            - Allowed values: `separated`
          - `labelConfig` (object, optional) — Styling applied to every field label.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
          - `valueConfig` (object, optional) — Styling applied to every field value.
            - `fontSize` (double, optional) — Font size in pixels. Defaults to 14.
            - `fontWeight` (enum or enum, optional) — Font weight. Defaults to 'normal'.
            - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
  - `layout` (string, required) — Grid layout as XML.
  - `overlays` (list of object or object or object, optional) — The modals, drawers, and popovers in this workbook and their contents.
    - Modal
      - `id` (string, required) — The identifier of the modal page.
      - `type` (enum, required) — Marks this page as a modal.
        - Allowed values: `modal`
      - `name` (string, required) — The name of the modal.
      - `modal` (object, optional) — The modal presentation options, including width, header, and footer buttons.
        - `width` (enum or enum or enum or enum or enum, optional) — The overlay width.
        - `header` (object, optional) — The header configuration, including title text and close-icon visibility.
          - `title` (string, optional) — The header title. Supports dynamic `{{formula}}` text.
          - `showCloseIcon` (enum or enum, optional) — Whether the header shows the close button.
        - `footer` (object, optional) — The footer with primary and secondary buttons.
          - `primaryCta` (object, optional) — The primary footer button.
            - `visible` (enum or enum, optional) — Whether the button is shown.
            - `text` (string, optional) — The button label. Supports dynamic `{{formula}}` text.
          - `secondaryCta` (object, optional) — The secondary footer button.
            - `visible` (enum or enum, optional) — Whether the button is shown.
            - `text` (string, optional) — The button label. Supports dynamic `{{formula}}` text.
      - `singleRowContainer` (object, optional) — Pins the modal to one row of a source: the elements inside it show that row. Omit for an ordinary modal.
        - `source` (object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The data source that supplies the displayed row.
          - Warehouse Table
            - `connectionId` (string, required) — The identifier of the connection to the data platform.
            - `path` (list of string, required) — The path of the object in the data platform.
            - `kind` (enum, required)
          - CSV Table
            - `connectionId` (string, required) — The identifier of the connection to the data platform.
            - `kind` (enum, required)
            - `inodeId` (string, required) — The identifier of the table created from a CSV.
          - Metric View
            - `connectionId` (string, required) — The identifier of the connection to the data platform.
            - `path` (list of string, required) — The path of the object in the data platform.
            - `kind` (enum, required)
          - Semantic View
            - `connectionId` (string, required) — The identifier of the connection to the data platform.
            - `path` (list of string, required) — The path of the object in the data platform.
            - `kind` (enum, required)
          - Custom SQL
            - `connectionId` (string, required) — The identifier of the connection to the data platform.
            - `kind` (enum, required)
            - `statement` (string, required) — The custom SQL statement used in the element.
          - Table
            - `kind` (enum, required)
            - `elementId` (string, required) — The identifier of the table in this data model.
            - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
          - Data Model
            - `dataModelId` (string, required) — The identifier of the data model source.
            - `elementId` (string, required) — The identifier of the table in the referenced data model.
            - `kind` (enum, required)
            - `groupingId` (string, optional) — The identifier of the grouping to apply to the table.
          - Code Output
            - `kind` (enum, required)
            - `elementId` (string, required) — The identifier of the code (Python) element whose output to display.
            - `output` (string, required) — Name of the code element's output — the sigma.output('name', …) name — to display.
          - Join
            - `kind` (enum, required)
            - `joins` (list of object, required) — A list of the joins and their definitions. The left of each join must be either the primary source or the right of some other join.
            - `name` (string, optional) — The name of the join. Defaults to the name of the primary source.
            - `primarySource` (object or object or object or object, optional) — The primary/head source of the join. If not specified, it is inferred as the unique source that appears on the left of some join but never on the right.
          - Union
            - `kind` (enum, required)
            - `sources` (list of object or object or object or object, required) — The identifiers of the sources in the union.
            - `matches` (list of object, required) — The union output columns and the matched source columns that comprise them.
          - Unnest
            - `kind` (enum, required)
            - `source` (object or object or object or object, required) — The source containing the array column to unnest.
            - `arrayColumn` (string, required) — The variant column containing arrays to unnest.
            - `valueColumn` (string, required) — The name of the generated column containing array values.
            - `outputColumns` (list of string, required) — The columns included in the unnest output.
            - `indexColumn` (string, optional) — The name of the generated zero-based array index column.
            - `preserveAllSourceRows` (enum or enum, optional) — Whether to preserve rows whose array column is null or empty.
        - `keyColumnId` (string, required) — The ID of the source column that identifies which row is displayed. Must be a column declared on the source.
        - `keyColumnValue` (boolean or double or string or string, optional, nullable) — The key-column value of the row to display. Must match the key column type. Omit to pin no row.
      - `actions` (list of object, optional) — The actions on the modal. Each action's `trigger` must be one of `on-primary-cta-click`, `on-secondary-cta-click`, or `on-close`.
        - `id` (string, required) — The identifier of the action sequence.
        - `trigger` (enum or enum or enum or enum or enum or enum or enum or enum or object or object or object, required) — The user interaction that initiates this action, such as a button click or cell selection.
          - object
            - `on` (enum or enum or enum or enum or enum or enum or enum or enum, required)
            - `condition` (object or object or object or object or object, required)
          - object
            - `on` (enum, required)
            - `menuItemId` (string, required) — The customContextMenu item's id this trigger targets.
            - `condition` (object or object or object or object or object, optional)
          - object
            - `kind` (enum, required)
            - `actionTriggerId` (string, required) — The identifier of the action trigger that fires this action.
            - `condition` (object or object or object or object or object, optional)
        - `effects` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The effects that run when the trigger occurs.
          - If/Else
            - `effect` (enum, required)
            - `if` (object, required) — Runs when its condition is true.
            - `elseif` (list of object, optional) — Additional branches, evaluated in order if `if` does not match.
            - `else` (object, optional) — Runs when no branch condition matches.
        - `name` (string, optional) — Optional display name for the action.
        - `state` (enum or enum, optional) — Whether the action runs. Defaults to `enabled`.
        - `successToast` (object, optional) — The message shown after this action runs successfully.
          - `showMessage` (enum or enum, required) — Whether the `message` line renders below the title of the action success message.
          - `title` (string, optional) — The title of the action success message. Supports dynamic `{{formula}}` text.
          - `message` (string, optional) — The message displayed to the user when the action completes successfully.
        - `summary` (string, optional) — A description of what this action sequence does.
      - `backgroundImage` (object, optional) — The background image for the modal. The URL supports dynamic `{{formula}}` text.
        - `source` (object or object, required) — The image source. Either an external URL (supports dynamic `{{formula}}` text) or an image uploaded into Sigma.
          - External URL
            - `kind` (enum, required)
            - `url` (string, required) — The external image URL. Supports dynamic `{{formula}}` text.
          - Uploaded Image
            - `kind` (enum, required)
            - `key` (string, required) — The identifier for an image uploaded to Sigma.
        - `style` (object, optional) — The image sizing and alignment within the element.
          - `fit` (enum or enum or enum or enum or enum, optional) — How the image fits the container.
          - `horizontalAlign` (enum or enum or enum, optional) — The horizontal alignment of the image within its container.
          - `verticalAlign` (enum or enum or enum, optional) — The vertical alignment of the image within its container.
          - `tiling` (enum or enum, optional) — The tiling behavior for the image. `none` displays a single image (default). `repeat` tiles the image to fill the container.
      - `backgroundColor` (string or string or object, optional) — The page background color. A hex code, `rgb()` value, or theme reference.
        - object
          - `kind` (enum, required)
            - Allowed values: `theme`
          - `ref` (string, required)
    - Drawer
      - `id` (string, required) — The identifier of the drawer page.
      - `type` (enum, required) — Marks this page as a drawer.
        - Allowed values: `drawer`
      - `name` (string, required) — The name of the drawer.
      - `drawer` (object, optional) — The presentation of the drawer, including width, header, and page overlay.
        - `width` (enum or enum or enum or enum or enum, optional) — The overlay width.
        - `header` (object, optional) — The header configuration, including title text and close-icon visibility.
          - `title` (string, optional) — The header title. Supports dynamic `{{formula}}` text.
          - `showCloseIcon` (enum or enum, optional) — Whether the header shows the close button.
        - `showShadow` (enum or enum, optional) — Whether to display the drawer as a page overlay, dimming the page behind it when open. Either `shown` to dim the background page or `hidden` for none.
      - `actions` (list of object, optional) — The actions triggered by the drawer, on close.
        - `id` (string, required) — The identifier of the action sequence.
        - `trigger` (enum or enum or enum or enum or enum or enum or enum or enum or object or object or object, required) — The user interaction that initiates this action, such as a button click or cell selection.
          - object
            - `on` (enum or enum or enum or enum or enum or enum or enum or enum, required)
            - `condition` (object or object or object or object or object, required)
          - object
            - `on` (enum, required)
            - `menuItemId` (string, required) — The customContextMenu item's id this trigger targets.
            - `condition` (object or object or object or object or object, optional)
          - object
            - `kind` (enum, required)
            - `actionTriggerId` (string, required) — The identifier of the action trigger that fires this action.
            - `condition` (object or object or object or object or object, optional)
        - `effects` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The effects that run when the trigger occurs.
          - If/Else
            - `effect` (enum, required)
            - `if` (object, required) — Runs when its condition is true.
            - `elseif` (list of object, optional) — Additional branches, evaluated in order if `if` does not match.
            - `else` (object, optional) — Runs when no branch condition matches.
        - `name` (string, optional) — Optional display name for the action.
        - `state` (enum or enum, optional) — Whether the action runs. Defaults to `enabled`.
        - `successToast` (object, optional) — The message shown after this action runs successfully.
          - `showMessage` (enum or enum, required) — Whether the `message` line renders below the title of the action success message.
          - `title` (string, optional) — The title of the action success message. Supports dynamic `{{formula}}` text.
          - `message` (string, optional) — The message displayed to the user when the action completes successfully.
        - `summary` (string, optional) — A description of what this action sequence does.
      - `backgroundImage` (object, optional) — Background image for the drawer. The URL supports dynamic `{{formula}}` text.
        - `source` (object or object, required) — The image source. Either an external URL (supports dynamic `{{formula}}` text) or an image uploaded into Sigma.
          - External URL
            - `kind` (enum, required)
            - `url` (string, required) — The external image URL. Supports dynamic `{{formula}}` text.
          - Uploaded Image
            - `kind` (enum, required)
            - `key` (string, required) — The identifier for an image uploaded to Sigma.
        - `style` (object, optional) — The image sizing and alignment within the element.
          - `fit` (enum or enum or enum or enum or enum, optional) — How the image fits the container.
          - `horizontalAlign` (enum or enum or enum, optional) — The horizontal alignment of the image within its container.
          - `verticalAlign` (enum or enum or enum, optional) — The vertical alignment of the image within its container.
          - `tiling` (enum or enum, optional) — The tiling behavior for the image. `none` displays a single image (default). `repeat` tiles the image to fill the container.
      - `backgroundColor` (string or string or object, optional) — The page background color. A hex code, `rgb()` value, or theme reference.
        - object
          - `kind` (enum, required)
            - Allowed values: `theme`
          - `ref` (string, required)
    - Popover
      - `id` (string, required) — The identifier of the popover page.
      - `type` (enum, required) — Marks this page as a popover.
        - Allowed values: `popover`
      - `name` (string, required) — The name of the popover.
      - `popover` (object, required) — Popover presentation: trigger button, width, spacing, padding, and element gap.
        - `triggerElementId` (string, required) — The identifier of the button that triggers the popover.
        - `width` (enum or enum or enum or enum or enum, optional) — Popover width breakpoint: x-small, small, medium, large, or x-large.
        - `spacing` (enum or enum or enum, optional) — The element spacing preset.
        - `padding` (enum, optional) — Set to 'none' to remove padding from the popover.
          - Allowed values: `none`
        - `elementGap` (enum or enum, optional) — Gap between popover elements: 'shown' (default) or 'hidden'.
      - `actions` (list of object, optional) — Actions fired by the popover when it closes.
        - `id` (string, required) — The identifier of the action sequence.
        - `trigger` (enum or enum or enum or enum or enum or enum or enum or enum or object or object or object, required) — The user interaction that initiates this action, such as a button click or cell selection.
          - object
            - `on` (enum or enum or enum or enum or enum or enum or enum or enum, required)
            - `condition` (object or object or object or object or object, required)
          - object
            - `on` (enum, required)
            - `menuItemId` (string, required) — The customContextMenu item's id this trigger targets.
            - `condition` (object or object or object or object or object, optional)
          - object
            - `kind` (enum, required)
            - `actionTriggerId` (string, required) — The identifier of the action trigger that fires this action.
            - `condition` (object or object or object or object or object, optional)
        - `effects` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The effects that run when the trigger occurs.
          - If/Else
            - `effect` (enum, required)
            - `if` (object, required) — Runs when its condition is true.
            - `elseif` (list of object, optional) — Additional branches, evaluated in order if `if` does not match.
            - `else` (object, optional) — Runs when no branch condition matches.
        - `name` (string, optional) — Optional display name for the action.
        - `state` (enum or enum, optional) — Whether the action runs. Defaults to `enabled`.
        - `successToast` (object, optional) — The message shown after this action runs successfully.
          - `showMessage` (enum or enum, required) — Whether the `message` line renders below the title of the action success message.
          - `title` (string, optional) — The title of the action success message. Supports dynamic `{{formula}}` text.
          - `message` (string, optional) — The message displayed to the user when the action completes successfully.
        - `summary` (string, optional) — A description of what this action sequence does.
      - `backgroundColor` (string or string or object, optional) — The page background color. A hex code, `rgb()` value, or theme reference.
        - object
          - `kind` (enum, required)
            - Allowed values: `theme`
          - `ref` (string, required)
  - `panels` (list of object or object, optional) — The definitions of page headers and sidebars in this document.
    - PageHeader
      - `id` (string, required) — The identifier of the page header.
      - `type` (enum, required) — Identifies this panel as a page header.
        - Allowed values: `header`
      - `title` (string, optional) — The display name of the header.
      - `pages` (list of string, optional) — Ids of the pages this panel is applied to. A page may have at most one header and one sidebar, and only normal pages can carry panels (not modals or drawers). Omit when the panel is defined but unassigned.
      - `config` (object, optional) — The header presentation, including scroll behavior, border, background, and height.
        - `scroll` (enum or enum, optional) — How the panel behaves as the page scrolls. 'sticky' pins it in place; 'none' lets it scroll away. Defaults to 'sticky'.
        - `borderStyle` (enum or enum or enum, optional) — The border drawn below the header. One of `line`, `shadow`, or `none`. `shadow` applies only when `scroll` is `sticky`.
        - `backgroundColor` (string, optional) — Panel background color. Omit to follow the theme.
    - PageSidebar
      - `id` (string, required) — The identifier of the page sidebar.
      - `type` (enum, required) — Identifies this panel as a page sidebar.
        - Allowed values: `sidebar`
      - `title` (string, optional) — The display name of the sidebar.
      - `pages` (list of string, optional) — Ids of the pages this panel is applied to. A page may have at most one header and one sidebar, and only normal pages can carry panels (not modals or drawers). Omit when the panel is defined but unassigned.
      - `width` (enum or enum or enum, optional) — Sidebar width preset. One of `small` (200px), `medium` (260px), or `large` (400px). Defaults to `medium`.
      - `config` (object, optional) — The sidebar presentation, including scroll behavior, border, and background color.
        - `scroll` (enum or enum, optional) — How the panel behaves as the page scrolls. 'sticky' pins it in place; 'none' lets it scroll away. Defaults to 'sticky'.
        - `borderStyle` (enum or enum, optional) — The border style for the sidebar.
        - `backgroundColor` (string, optional) — Panel background color. Omit to follow the theme.
  - `settings` (object, optional) — The document-level settings. Accepts `theme`, and `navigation` on a workbook. A report accepts `theme` alone.
    - `theme` (object, optional) — The document theme. Either the name of a theme in the organization or a built-in theme. Optionally, applies per-field overrides to the theme for colors and fonts.
      - `name` (enum or enum or enum or string, optional) — The name of a built-in theme (`Light`, `Dark`, or `Surface`) or the UUID of an organization theme. Omit to use the organization default theme, or `Light` when the organization has no default.
      - `overrides` (object, optional) — Customizations applied on top of the base theme selected by `name`, or the document's default theme when `name` is omitted.
        - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
        - `categoricalScheme` (string or list of string, optional) — The categorical color palette, as a palette name or custom hex array. Defaults to `superbloom`.
        - `colorOverrides` (list of object, optional) — Overrides for particular layout theme colors as hex codes. Keys match the theme color inspector (e.g. backgroundCanvas, elementBackground).
          - `name` (string, required) — ColorTheme slot name (matches the theme color inspector, e.g. backgroundCanvas).
          - `color` (string, required)
        - `colors` (object, optional)
          - `text` (string, optional) — The primary text color, as a hex code.
          - `highlight` (string, optional) — The highlight or accent color, as a hex code. Maps to the theme's `$primary` color.
          - `surface` (string, optional) — The surface color, as a hex code.
          - `success` (string, optional) — The success color, as a hex code.
          - `warning` (string, optional) — The warning color, as a hex code.
          - `danger` (string, optional) — The danger color, as a hex code.
          - `darkMode` (enum or enum, optional) — Whether dark color mode is on. Defaults to `hidden`.
        - `divergingScheme` (string, optional) — The named diverging color scheme. Defaults to `blueorange`.
        - `elementBorder` (object, optional)
          - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
            - object
          - `width` (double, optional) — Element border width in pixels (0–3).
        - `fonts` (object, optional)
          - `dataFont` (string, optional) — The font family for workbook data. Defaults to `Roboto`.
          - `textFont` (string, optional) — The font family for non-data text, like element titles, descriptions, and table headers.
        - `hasCards` (enum or enum, optional) — Whether elements are framed as cards (with a border, background, and padding). Defaults to `shown`.
        - `invertTooltipColors` (enum or enum, optional) — Whether to invert text and background colors in visualization tooltips. Defaults to `shown`.
        - `layoutColors` (object, optional)
          - `useElementForeground` (enum or enum, optional) — Whether elements render above the canvas.
        - `maxPageWidth` (double, optional) — Max page width in pixels when pageWidth is custom (minimum 600).
        - `pageWidth` (enum or enum or enum or enum, optional) — The page content width.
        - `sequentialScheme` (string, optional) — The named sequential color scheme. Defaults to `blues`.
        - `space` (object, optional)
          - `showElementPadding` (enum or enum, optional) — Whether padding around elements is shown. Defaults to `shown`.
          - `unit` (enum or enum or enum, optional) — The element spacing preset.
        - `tableStyles` (object or object, optional) — The visual styling, including background color, border, corner shape, and padding.
          - object
            - `padding` (enum, required) — The padding around the element. Set to none to remove padding. `borderWidth` and `borderColor` cannot be set alongside it.
            - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
          - object
            - `backgroundColor` (string or string or object or enum, optional) — Element background color (hex, rgb(), theme reference, or "transparent").
            - `borderRadius` (enum or enum or enum, optional) — The corner shape. Omit to inherit the workbook theme.
            - `borderWidth` (double, optional) — The border width, in pixels. Cannot be set when `padding` is `none`.
            - `borderColor` (string or string or object, optional) — The border color. A hex code, `rgb()` value, or theme reference. Cannot be set when `padding` is `none`.
        - `titleFont` (object, optional)
          - `color` (string or string or object, optional) — A hex color (`#rgb` or `#rrggbb`), an `rgb()` value (e.g. `rgb(0, 0, 255)`), or a theme color reference. `rgba()` is not supported.
            - object
          - `fontSize` (double, optional) — Title font size in pixels (6–96).
          - `fontWeight` (enum or enum, optional)
    - `navigation` (object, optional) — The workbook navigation settings for page headers, page sidebars, and page tabs. Omitting it drops any previously stored navigation settings.
      - `pageHeader` (enum or enum, optional) — Whether page headers are enabled in the workbook. Defaults to `disabled`. A page also needs a header panel assigned before one renders.
      - `pageSidebar` (enum or enum, optional) — Whether page sidebars are enabled in the workbook. Defaults to `disabled`. A page also needs a sidebar panel assigned before one renders.
      - `primary` (enum or enum, optional) — Which panel overlays the other when a page has both a header and a sidebar. If panels have different scroll styles, the fixed panel overlays the scrolling panel. Defaults to `sidebar`.
      - `pageTabsInViewMode` (enum or enum, optional) — Whether viewers see the page tab bar. Defaults to `shown`.
  - `agents` (list of object, optional) — The agents defined in the workbook. Reference one from a chat element using `agentId`.
    - `id` (string, required) — The identifier of the agent.
    - `instructions` (string, required) — Instructions that guide the agent. Use `{{formula}}` for dynamic values, `@dataSource("elementId")` for configured data sources, and `@tool("toolId")` for configured tools.
    - `name` (string, optional) — Display name for the agent.
    - `description` (string, optional) — The description of the agent.
    - `greeting` (object or object, optional) — The greeting message for the agent. Set `mode` to `static` with a `message`, or `generated` with a `prompt`. Omit for the product default.
      - Fixed greeting
        - `mode` (enum, required)
          - Allowed values: `static`
        - `message` (string, required) — The first message an agent displays when the chat opens. Not generated by the AI provider. Supports dynamic `{{formula}}` text.
      - Generated greeting
        - `mode` (enum, required)
          - Allowed values: `generated`
        - `prompt` (string, required) — The prompt the agent uses to generate the first message displayed when the chat opens. Supports dynamic `{{formula}}` text.
    - `dataSources` (list of object, optional) — The data elements or data model tables the agent can access.
      - `kind` (enum, required)
        - Allowed values: `table`
      - `elementId` (string, required) — The identifier of a workbook element, such as a table or chart, the agent can read from.
    - `tools` (list of object or object or object or object, optional) — The tools the agent can invoke to take action or enrich insights.
      - MCP connector
        - `toolId` (string, required) — The identifier of the tool within this agent. Must not contain '[', ']', '/', or '\', and must not have leading or trailing whitespace.
        - `kind` (enum, required)
          - Allowed values: `mcp-connector`
        - `connectorId` (string, required) — The UUID of the MCP connector.
        - `name` (string, required) — The display name of the MCP connector.
      - Warehouse agent
        - `toolId` (string, required) — The identifier of the tool within this agent. Must not contain '[', ']', '/', or '\', and must not have leading or trailing whitespace.
        - `kind` (enum, required)
          - Allowed values: `warehouse-agent`
        - `connectionId` (string, required) — The identifier of the connection to the data platform.
        - `path` (list of string, required) — The path of the object in the data platform.
        - `description` (string, optional) — A description of when the agent should invoke this warehouse agent.
      - Search service
        - `toolId` (string, required) — The identifier of the tool within this agent. Must not contain '[', ']', '/', or '\', and must not have leading or trailing whitespace.
        - `kind` (enum, required)
          - Allowed values: `search-service`
        - `description` (string, required) — A description of what this search service can retrieve, used by the agent to decide when to call it.
        - `connectionId` (string, required) — The identifier of the connection to the data platform.
        - `path` (list of string, required) — The path of the object in the data platform.
      - Action
        - `toolId` (string, required) — The identifier of the tool within this agent. Must not contain '[', ']', '/', or '\', and must not have leading or trailing whitespace.
        - `kind` (enum, required)
          - Allowed values: `action`
        - `name` (string, required) — The display name of the action tool.
        - `description` (string, required) — A description of what this tool does and when the agent should invoke it.
        - `steps` (list of object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object or object, required) — The steps the agent runs when it invokes this action tool.
          - Sequence reference
            - `kind` (enum, required)
            - `sequenceId` (string, required) — The identifier of an action sequence in the workbook.
            - `name` (string, optional) — Optional display name for this step.
        - `requiresApproval` (boolean, optional) — Whether the agent must pause to get user approval before running this tool. Defaults to `false`.
  - `automatedActions` (list of object, optional) — The action sequences that run automatically on a schedule or webhook trigger.
    - `effects` (list of object, required) — The actions that run when the schedule triggers.
      - `agentId` (string, required) — The identifier of the Sigma agent to run in this workbook.
      - `effect` (enum, required)
        - Allowed values: `call-agent`
      - `prompt` (string, required) — The instructions passed to the agent when the action runs.
      - `actionVariables` (list of object, optional) — The action variables populated from the agent response.
        - `id` (string, required) — The identifier of the action variable for the agent to return the value from.
        - `type` (enum or enum or enum or enum or enum, required) — Scalar data type of the action variable.
        - `name` (string, optional) — Display name for the action variable.
    - `id` (string, required) — The stable identifier for this automated action sequence.
    - `schedule` (object, required) — The configuration of a recurring schedule. Includes a cron expression and timezone.
      - `cronSpec` (string, required) — The cron expression that determines when the scheduled action runs. E.g., `0 9 * * 1` runs every Monday at 9:00 AM.
      - `timezone` (string, required) — The IANA timezone used to evaluate the cron expression.
    - `trigger` (enum, required) — Runs the automated action sequence on a recurring schedule.
      - Allowed values: `schedule`
    - `name` (string, optional) — Optional display name for the automated action sequence.
    - `state` (enum or enum, optional) — Whether the automated action sequence is turned on or off.
- `documentVersion` (double, optional) — When provided, update only if the workbook is still at this document version.

## Response

### 200

The response body.

- `workbookId` (string, required) — Unique identifier of the workbook.
- `workbookUrlId` (string, required)
- `name` (string, required)
- `url` (string, required)
- `path` (string, required)
- `latestVersion` (double, required) — The most recently published document version of the workbook.
- `ownerId` (string, required)
- `createdBy` (string, required) — The identifier of the user who created this object.
- `updatedBy` (string, required) — The identifier of the user or process that last updated this object.
- `createdAt` (datetime, required) — When the object was created.
- `updatedAt` (datetime, required) — When the object was last updated.
- `isArchived` (boolean, optional)
- `tags` (list of object, optional)
  - `versionTagId` (string, required) — Unique identifier of the tag.
  - `name` (string, required)
  - `sourceWorkbookVersion` (double, required)
  - `taggedWorkbookId` (string, required) — Unique identifier of the tagged workbook.
  - `workbookTaggedAt` (datetime, required)
- `description` (string, optional)
- `taggedSourceUrlId` (string, optional) — 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.

## Examples

**Request**

```json
{
  "contents": {
    "schemaVersion": 1,
    "kind": "workbook",
    "pages": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "elements": [
      null
    ],
    "layout": "string"
  }
}
```

**Response**

```json
{
  "workbookId": "string",
  "workbookUrlId": "string",
  "name": "string",
  "url": "string",
  "path": "string",
  "latestVersion": 1.1,
  "ownerId": "string",
  "createdBy": "string",
  "updatedBy": "string",
  "createdAt": "2024-01-15T09:30:00Z",
  "updatedAt": "2024-01-15T09:30:00Z",
  "isArchived": true,
  "tags": [
    {
      "versionTagId": "string",
      "name": "string",
      "sourceWorkbookVersion": 1.1,
      "taggedWorkbookId": "string",
      "workbookTaggedAt": "2024-01-15T09:30:00Z"
    }
  ],
  "description": "string",
  "taggedSourceUrlId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://api.sigmacomputing.com/v2/workbooks/workbookId/contents"

payload = { "contents": {
        "schemaVersion": 1,
        "kind": "workbook",
        "pages": [
            {
                "id": "string",
                "name": "string"
            }
        ],
        "elements": [None],
        "layout": "string"
    } }
headers = {
    "Authorization": "<token>.",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.sigmacomputing.com/v2/workbooks/workbookId/contents';
const options = {
  method: 'PUT',
  headers: {Authorization: '<token>.', 'Content-Type': 'application/json'},
  body: '{"contents":{"schemaVersion":1,"kind":"workbook","pages":[{"id":"string","name":"string"}],"elements":[null],"layout":"string"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sigmacomputing.com/v2/workbooks/workbookId/contents"

	payload := strings.NewReader("{\n  \"contents\": {\n    \"schemaVersion\": 1,\n    \"kind\": \"workbook\",\n    \"pages\": [\n      {\n        \"id\": \"string\",\n        \"name\": \"string\"\n      }\n    ],\n    \"elements\": [\n      null\n    ],\n    \"layout\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<token>.")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.sigmacomputing.com/v2/workbooks/workbookId/contents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<token>.'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"contents\": {\n    \"schemaVersion\": 1,\n    \"kind\": \"workbook\",\n    \"pages\": [\n      {\n        \"id\": \"string\",\n        \"name\": \"string\"\n      }\n    ],\n    \"elements\": [\n      null\n    ],\n    \"layout\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.put("https://api.sigmacomputing.com/v2/workbooks/workbookId/contents")
  .header("Authorization", "<token>.")
  .header("Content-Type", "application/json")
  .body("{\n  \"contents\": {\n    \"schemaVersion\": 1,\n    \"kind\": \"workbook\",\n    \"pages\": [\n      {\n        \"id\": \"string\",\n        \"name\": \"string\"\n      }\n    ],\n    \"elements\": [\n      null\n    ],\n    \"layout\": \"string\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('PUT', 'https://api.sigmacomputing.com/v2/workbooks/workbookId/contents', [
  'body' => '{
  "contents": {
    "schemaVersion": 1,
    "kind": "workbook",
    "pages": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "elements": [
      null
    ],
    "layout": "string"
  }
}',
  'headers' => [
    'Authorization' => '<token>.',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.sigmacomputing.com/v2/workbooks/workbookId/contents");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "<token>.");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"contents\": {\n    \"schemaVersion\": 1,\n    \"kind\": \"workbook\",\n    \"pages\": [\n      {\n        \"id\": \"string\",\n        \"name\": \"string\"\n      }\n    ],\n    \"elements\": [\n      null\n    ],\n    \"layout\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<token>.",
  "Content-Type": "application/json"
]
let parameters = ["contents": [
    "schemaVersion": 1,
    "kind": "workbook",
    "pages": [
      [
        "id": "string",
        "name": "string"
      ]
    ],
    "elements": [],
    "layout": "string"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.sigmacomputing.com/v2/workbooks/workbookId/contents")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```