Manage reports as code (Beta)

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.

You can use the Sigma API to retrieve, create, and update reports based on a JSON or YAML representation. These endpoints enable a programmatic workflow, allowing you to manage and review reports without using the Sigma UI.

Use these endpoints when you want to:

Develop reports using AI assistants
Automate and scale the creation and management of reports
Integrate report development with external tools

About representing reports as code

Sigma offers programmatic report API endpoints, which use a JSON or YAML representation of a report as the input and output. The representation, sometimes referred to as a schema or specification, defines the structure of the report, including its data sources, pages, and elements. Additionally, you can specify the configuration of elements and their layout on the report page to the pixel level.

Using these endpoints, you can programmatically create and manage reports using data elements like tables and charts, as well as formatting features like headers and footers. To see supported and unsupported report features, see Limitations.

The representation does not include data from your data sources. It lists IDs, which reference the data sources, and then describes how to arrange the contents of the data sources in the report. For example, instead of listing individual records like a CSV file, the representation lists the columns of a table and the connection those columns are sourced from.

Sigma increments the schemaVersion field when it releases a new version of the specification. The schemaVersion field is required when creating or updating a report to ensure backward compatibility.

User requirements

The ability to create and manage reports from code requires the following:

You must be the report owner or be granted Can edit access to the report.
You must have developer credentials for the Sigma API. For more information, see Get started with the Sigma REST API.
The user associated with your API credentials must be assigned an account type with the Create, edit, and publish reports permission enabled.

Limitations

Most report features and element types can be represented as code, including all table and control elements, most chart types, text, image, divider, embed, and plugin elements, page size and margins, headers, footers, page numbers, paginated tables, element layering, and repeated containers. However, some features and combinations of features are not supported. Consult the following resources for up-to-date information about what features are represented and how to use them:

To see the full schema definition for the representation, see the Sigma OpenAPI specification.
To review every element type, property, and value the representation accepts, see the endpoint documentation for Create a report.
For many common features and settings, you can see an example compared with the steps to create it in the UI in the Report representation example library.

The following list is non-exhaustive and describes some of the limitations of the current representation:

The following chart types are not represented: Box plot, waterfall, Sankey, funnel, and gauge.
CSV input tables are not represented.
Report and page-level settings are not represented, such as background color, themes, and fonts.
Some configurations of supported elements are not represented, such as some chart customizations and data entry for input tables.
Synced controls are not supported when creating or updating a report.

Endpoints for managing reports as code

The code representation is carried by the main report endpoints. In each case, the representation travels in a contents object:

Task	Endpoint
Retrieve a representation	Get a report (`GET /v2/reports/{reportId}?includeContents=true`)
Create a report from a representation	Create a report (`POST /v2/reports`)
Update a report from a representation	Update a report from a code representation (`PUT /v2/reports/{reportId}/contents`)

Get the code representation of an existing report

To retrieve the code representation of an existing report, call the Get a report endpoint with the reportId for the report and the query parameter includeContents=true:

Identify the existing report you want the representation for by name, owner, or other details.
Call the List reports endpoint to retrieve the reportId for the report.
Call the Get a report endpoint, passing the reportId as a path parameter and includeContents=true as a query parameter.

The endpoint returns the code representation of the report.

For step-by-step instructions, see Get the code representation of a report.

Create a report from a code representation

To create a report from a code representation, call the Create a report endpoint with the code representation in the contents field of the request body.

Prepare a code representation of the report you want to create. This might be based on a representation retrieved from an existing report, or it might be a new representation. For example representations, see the Example library.
Call the Create a report endpoint, passing the code representation as contents in the request body.

The endpoint creates the report and returns the reportId in the response body.

For step-by-step instructions, see Create a report from a code representation.

Update an existing report from a code representation

To update an existing report from a code representation, call the Update a report from a code representation endpoint with the code representation in the contents field of the request body.

Identify the existing report you want to update, by name, owner, or other details.
Call the List reports endpoint to retrieve the reportId for the report.
Prepare a code representation of the report with the updates you want to apply. For an example, see the Example library.
Call the Update a report from a code representation endpoint, passing the reportId as a path parameter and the code representation as contents in the request body.

The endpoint updates the report.

For step-by-step instructions, see Update a report from a code representation.

The Update a report from a code representation 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.

Verify a report code representation

To verify that a report code representation is valid before creating a report from it, call the Verify a report code representation endpoint, passing the code representation in the request body.

Identify or prepare the code representation you want to verify.
Call the Verify a report code representation endpoint to check if the representation is valid.