Update a report from a code representation (Deprecated)

Deprecation notice: This endpoint is deprecated. Instead, use PUT /v2/reports/{reportId}/contents.

This endpoint replaces a report with a report defined in a code representation. This creates a new version of the report, which is accessible from the Sigma UI.

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

For more information on managing reports programmatically, see Manage reports as code. For more information on using this endpoint, including end-to-end instructions, see Get the code representation of a report.

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 format of the representation is YAML. To use JSON, add the header Content-Type: application/json.
• You can define pixel layout using XML in the 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". For more information, see Customize the layout of a report in code representation.
• Use the panels field for header and footer panel definitions, elements, and page membership (pages). Panel pixel placements live in the same layout XML as page placements.
• You can combine multiple YAML documents to create one report representation. For more information, see Prepare a representation from multiple YAML documents.
• To retrieve the representation of an existing report, use the /v2/reports/{reportId}/spec endpoint.
• To create a new report from code, use the /v2/reports/spec endpoint.
• 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.
• 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.