Update a report from a code representation (Beta)

This endpoint replaces a report with a report defined in a code representation. You can programmatically update the report's structure, metadata, and contents. This creates a new version of the report, 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 reports** permission. - To perform this operation, you must use API credentials owned by a user with **Can edit** access for the report. ### Usage notes - The default response format is JSON. To use YAML, add the header `Accept: application/yaml`. - You can define pixel layout using XML in the `contents.layout` field. Top-level `Page` and `Panel` roots may appear together; each `Element` uses absolute `x`/`y`/`width`/`height` attributes in pixels. `Panel` roots require `type="header"` or `type="footer"`. - You can combine multiple YAML documents to create one report 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 report, use `GET /reports/{reportId}?includeContents=true`. - To create a new report from code, use `POST /reports` with `contents` in the request body. - When `documentVersion` is provided in the request body, the update fails when the report has changed since that version. If omitted, the update preserves last-write-wins behavior. - The endpoint only supports updates to the `contents` object. Report metadata sent alongside `contents` -- including `name`, `folderId`, and `description` -- is ignored, so you can submit a `GET` response unchanged. To rename or move a report, 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 report in the request body. ### Usage scenarios - **Agentic workflows**: Agents can use these endpoints to directly manage report contents in code. - **Automation**: If you want to update several reports across one or more organizations, or in response to external events, you can use this endpoint to programmatically update the reports. - **Integration**: Using this endpoint, you can update reports based on external data sources or integrate Sigma with other tools and platforms.