> 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 report from a code representation (Beta) > Update an existing Sigma report from a JSON or YAML code representation using the Sigma API Update report from code endpoint. This documentation describes one or more public beta features that are in development. Beta features are subject to quick, iterative changes; therefore the current user experience in the Sigma service can differ from the information provided in this page. This page should not be considered official published documentation until Sigma removes this notice and the beta flag on the corresponding feature(s) in the Sigma service. For the full beta feature disclaimer, see [Beta features](/docs/sigma-product-releases#beta-features). You can update an existing report from a code representation by calling the [Update a report from a code representation](/reference/update-report-contents) endpoint with the code representation in the `contents` field of the request body. This document provides step-by-step instructions for using this endpoint to update a report from a code representation. For more information on working with reports programmatically, see [Manage reports as code](/docs/manage-reports-as-code). ## User requirements The ability to update a report from a code representation requires the following: * You must have developer credentials for the Sigma API. For more information, see [Get started with the Sigma REST API](/reference/get-started-sigma-api). * The user associated with your API credentials must be assigned an [account type](/docs/account-type-and-license-overview) with the **Create, edit, and publish reports** permission enabled. * You must be the document owner or be granted **Can edit** [access](/docs/folder-and-document-permissions) to the report. ## Generate API client credentials and an API access token To start, you must generate credentials for the Sigma API. These credentials are used to retrieve an access token, which is required to make requests to the API. For step-by-step instructions on generating developer credentials in Sigma and using them to authenticate to the Sigma API, see the instructions in [Generate client credentials](/reference/generate-client-credentials). ## Identify the report and retrieve the report ID To update an existing report from a code representation, you must know the unique `reportId` for that report. After you identify the report you want to update, you can call the [List reports](/reference/list-reports) endpoint to retrieve the `reportId`: 1. Go to your **Home** page. 2. In the navigation menu, select **Documents**. 3. Click the **Document type** ![](https://sigma-docs-screenshots.s3.us-west-2.amazonaws.com/Icons/caret.svg) filter and select **Reports**. The list of your reports appears. 4. Identify the report you want to update, by name, owner, or other details. 5. Make a GET request to the [List reports](/reference/list-reports) endpoint like the following: #### List reports request format ```shell curl --request GET \ --url /v2/reports \ --header 'Authorization: Bearer ' \ --header 'accept:application/json' \ --header 'content-type: application/x-www-form-urlencoded' ``` The response includes a list of reports in your organization, in the following format: #### List reports response format ```json { "entries": [ { "reportId": "", "reportUrlId": "", "createdBy": "", "updatedBy": "", "createdAt": "", "updatedAt": "", "name": "", "url": "", "path": "", "latestVersion": "", "ownerId": "", "description": "" }, { "reportId": "", "reportUrlId": "", "createdBy": "", "updatedBy": "", "createdAt": "", "updatedAt": "", "name": "", "tags": [ { "versionTagId": "", "tagName": "", "sourceVersion": "", "taggedReportId": "", "taggedAt": "" } ], "url": "", "path": "", "latestVersion": "", "ownerId": "" } ], "hasMore": , "total": , "nextPage": null } ``` 6. Identify the report you want to update, and copy the `reportId` to use with the [Update a report from a code representation](/reference/update-report-contents) endpoint. ## Prepare the representation To update an existing report from a code representation, you must prepare a valid code representation of the report with the updates you want to apply. You can base this on the existing report's representation, or construct an entirely new one. The [Update a report from a code representation](/reference/update-report-contents) endpoint does not support partial updates. To update a report, you must provide a complete representation of the report, even if you are only making minor changes. Sigma recommends retrieving the existing representation and basing your changes on that. The code representation you prepare can be passed into the request body of the [Update a report from a code representation](/reference/update-report-contents) endpoint to update the report. The body must include the `contents` object with its required `schemaVersion`, `kind`, `elements`, `pages`, and `layout` fields. The endpoint reads only `contents` and the optional `documentVersion`. Report metadata sent alongside `contents` — including `name`, `folderId`, and `description` — is ignored, so you can submit a response from the [Get a report](/reference/get-report) endpoint unchanged. The report stays in its existing folder. To rename or move a report, use the [Update a file](/reference/update-file) endpoint. Whenever you add or remove an element, update the `layout` to match. Every element in `contents.elements` must be placed in the `layout`, and a representation with an element the layout never references is rejected with an error naming that element, such as `elements[0]: element 'fWvU8grr1I' is not placed in layout`. 1. Using the `reportId` you identified in the previous section, follow the instructions in [Get the code representation of a report](/docs/get-the-code-representation-of-a-report) to get the current representation. For example, you might retrieve the representation for a report with a single table, like the following: #### YAML representation ```yaml reportId: 2b6e8f13-7a45-4c9d-b0e2-58f9a41c6d37 reportUrlId: 9mQp274XtRvL8k5CyNwZ3f createdBy: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s updatedBy: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s createdAt: '2026-09-16T14:58:01.492Z' updatedAt: '2026-09-16T15:13:41.089Z' name: BIKE_TRIPS url: https://staging.sigmacomputing.io/sigma-on-sigma/report/9mQp274XtRvL8k5CyNwZ3f path: My Documents/Sample Folder latestVersion: 2 ownerId: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s isArchived: false contents: schemaVersion: 1 elements: - id: qA9ArLmeWE kind: table source: connectionId: 82fa5c19-4b7e-4f03-9d6a-7c1e9f4b3a58 kind: warehouse-table path: - EXAMPLES - BIKES - TRIP columns: - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/ID formula: '[TRIP/Id]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION formula: '[TRIP/Duration]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/START_DATE formula: '[TRIP/Start Date]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/START_STATION_NAME formula: '[TRIP/Start Station Name]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/START_STATION_ID formula: '[TRIP/Start Station Id]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/END_DATE formula: '[TRIP/End Date]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/END_STATION_NAME formula: '[TRIP/End Station Name]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/END_STATION_ID formula: '[TRIP/End Station Id]' order: - inode-7cURxqD6vJwZzMcJ5KTiCZ/ID - inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION - inode-7cURxqD6vJwZzMcJ5KTiCZ/START_DATE - inode-7cURxqD6vJwZzMcJ5KTiCZ/START_STATION_NAME - inode-7cURxqD6vJwZzMcJ5KTiCZ/START_STATION_ID - inode-7cURxqD6vJwZzMcJ5KTiCZ/END_DATE - inode-7cURxqD6vJwZzMcJ5KTiCZ/END_STATION_NAME - inode-7cURxqD6vJwZzMcJ5KTiCZ/END_STATION_ID pages: - id: '1' name: Page 1 config: margin: 0 pageHeight: 1056 pageWidth: 816 kind: report layout: | documentVersion: 2 ``` 2. Make any desired changes to the `contents` object. For example, you might want to rename a table, add a new column, or remove an element. The report code representation does not support all report features. Unsupported features are silently dropped when you make a request to the [Get a report](/reference/get-report) endpoint. If you use a representation from that endpoint to create or update another report from code, it does not include the dropped features, even if they were present in the original report. In this example, most columns are removed from the representation, leaving only the *ID* and *Duration* columns: #### YAML representation ```yaml reportId: 2b6e8f13-7a45-4c9d-b0e2-58f9a41c6d37 reportUrlId: 9mQp274XtRvL8k5CyNwZ3f createdBy: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s updatedBy: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s createdAt: '2026-09-16T14:58:01.492Z' updatedAt: '2026-09-16T15:13:41.089Z' name: BIKE_TRIPS url: https://staging.sigmacomputing.io/sigma-on-sigma/report/9mQp274XtRvL8k5CyNwZ3f path: My Documents/Sample Folder latestVersion: 2 ownerId: pWvNzTqR3BmXe6LcYd8FA0K1oJh5s isArchived: false contents: schemaVersion: 1 elements: - id: qA9ArLmeWE kind: table source: connectionId: 82fa5c19-4b7e-4f03-9d6a-7c1e9f4b3a58 kind: warehouse-table path: - EXAMPLES - BIKES - TRIP columns: - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/ID formula: '[TRIP/Id]' - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION formula: '[TRIP/Duration]' order: - inode-7cURxqD6vJwZzMcJ5KTiCZ/ID - inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION pages: - id: '1' name: Page 1 config: margin: 0 pageHeight: 1056 pageWidth: 816 kind: report layout: | documentVersion: 2 ``` ## Call the Update a report from a code representation endpoint Finally, call the [Update a report from a code representation](/reference/update-report-contents) endpoint, passing the `reportId` as a path parameter and the updated code representation in the request body. The request format is as follows: #### Update a report from a representation request format ```shell curl --request PUT \ --url /v2/reports//contents \ --header 'Authorization: Bearer ' \ --header 'content-type: application/yaml' \ --data 'contents: schemaVersion: 1 kind: report elements: - id: qA9ArLmeWE kind: table source: connectionId: 82fa5c19-4b7e-4f03-9d6a-7c1e9f4b3a58 kind: warehouse-table path: - EXAMPLES - BIKES - TRIP columns: - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/ID formula: "[TRIP/Id]" - id: inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION formula: "[TRIP/Duration]" order: - inode-7cURxqD6vJwZzMcJ5KTiCZ/ID - inode-7cURxqD6vJwZzMcJ5KTiCZ/DURATION pages: - id: "1" name: Page 1 config: margin: 0 pageHeight: 1056 pageWidth: 816 layout: | ' ``` The endpoint updates the report with the new representation and returns the report metadata, including the new `latestVersion`. To avoid overwriting a change someone else made while you were preparing your update, include the `documentVersion` you retrieved alongside `contents` in the request body. If the report changed since that version, the update fails with a `stale_document_settings` error instead of replacing the newer contents. When you omit `documentVersion`, the last write wins.