> 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. # Create a report from a code representation (Beta) > Create a Sigma report from a JSON or YAML code representation using the Sigma API Create report from code representation 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 create a report from a code representation by calling the [Create a report](/reference/create-report) 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 create 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 create 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. ## 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). ## Prepare a code representation To create a report using the [Create a report](/reference/create-report) endpoint, you must first construct a valid code representation of a report. To see example representations with various features and configurations, see the [Example library](/docs/report-representation-example-library). You can prepare a representation using any of the following options: * [Prepare the representation manually](#prepare-the-representation-manually) * [Prepare a representation from multiple YAML documents](#prepare-a-representation-from-multiple-yaml-documents) * [Prepare the representation based on an existing report](#prepare-the-representation-based-on-an-existing-report) * [Prepare the representation using an AI assistant](#prepare-the-representation-using-an-ai-assistant) ### Prepare the representation manually You can prepare the code representation of a report manually by constructing JSON or YAML with the required fields. A valid request body has the following required fields, where `contents` is the representation itself: * `name`: The name of the report. * `folderId`: The ID of the folder to create the report in. * `contents`: An object describing the contents of the report. Required to create a report with any pages or elements. * `schemaVersion`: The version of the representation schema to use. * `kind`: The type of document the representation describes. For a report, the value is `report`. * `elements`: An array of every element in the report, across all pages and panels. Can be empty. * `pages`: An array of page objects. * `id`: An ID for the page. * `name`: The name of the page. * `layout`: An XML string that assigns each element to a page or panel and positions it. Every element in `contents.elements` must be placed in the `layout`, because the layout is what assigns an element to a page or panel. For more information, see [Customize the layout of a report in code representation](/docs/customize-the-layout-of-a-report-in-code-representation). Optionally, page setup features like page size and margins can be included in the `contents.config` field: * `config`: The report-level configuration. * `margin`: The report page margin in pixels. * `pageHeight`: The report page height in pixels. * `pageWidth`: The report page width in pixels. Because a valid code representation of a report can contain many nested objects with references to one another, Sigma does not recommend preparing large representations manually. See [Prepare the representation based on an existing report](#prepare-the-representation-based-on-an-existing-report) or [Prepare the representation using an AI assistant](#prepare-the-representation-using-an-ai-assistant) for alternative options to prepare a representation. As an example, the following POST request creates a report with one empty page in a specified folder: #### POST request example ```shell curl --request POST \ --url /v2/reports \ --header "Authorization: Bearer " \ --header 'content-type:application/json' \ --data '{"name":"Sample Report","folderId":,"contents":{"schemaVersion":1,"kind":"report","elements":[],"pages":[{"id":,"name":"Page 1"}],"layout":"\n\"/>\n"}}' ``` Retrieving that report with `includeContents=true` returns the representation as follows: #### YAML representation example ```yaml reportId: reportUrlId: createdBy: updatedBy: createdAt: updatedAt: name: Sample Report url: path: latestVersion: 1 ownerId: isArchived: false documentVersion: 1 contents: schemaVersion: 1 kind: report elements: [] pages: - id: name: Page 1 config: margin: 0 pageHeight: 1056 pageWidth: 816 layout: | ``` The `folderId` field is required, and a POST request without a top-level `folderId` is rejected. When you include `contents`, `contents.layout` is also required. The `contents.config` field is optional, and defaults are returned when you make a GET request for the representation of the same report. For more information on using the `layout` field to customize a report, see [Customize the layout of a report in code representation](/docs/customize-the-layout-of-a-report-in-code-representation). Add elements like tables, charts, and more to the representation by including them in the `contents.elements` array and placing each one in the `layout`. Headers and footers go in the `contents.panels` array, where each panel is a region repeated on every page. To learn about the configuration of an element in the representation, see the entry for that element in the [Report representation example library](/docs/report-representation-example-library). ### Prepare a representation from multiple YAML documents When preparing a code representation of a report, you can define the report contents in multiple YAML documents, and combine them into one report when calling the [Create a report](/reference/create-report) endpoint. To send YAML, add the header `Content-Type: application/yaml`. As an example, the following POST request creates an empty report in a specified folder with two pages, each defined in a separate YAML document: #### POST request example ```shell curl --request POST \ --url /v2/reports \ --header "Authorization: Bearer " \ --header "content-type: application/yaml" \ --data 'name: Sample Report folderId: contents: schemaVersion: 1 kind: report elements: [] pages: - id: name: Page 1 layout: | --- contents: pages: - id: name: Page 2' ``` Retrieving that report with `includeContents=true` returns the representation as follows: #### YAML representation example ```yaml reportId: reportUrlId: createdBy: updatedBy: createdAt: updatedAt: name: Sample Report url: path: latestVersion: 1 ownerId: isArchived: false documentVersion: 1 contents: schemaVersion: 1 kind: report elements: [] pages: - id: name: Page 1 - id: name: Page 2 config: margin: 0 pageHeight: 1056 pageWidth: 816 layout: | ``` When combining multiple YAML documents in one report code representation, each document contributes entries to the `contents.pages` and `contents.elements` arrays, which the API merges into a single report. A single page cannot draw its contents from more than one document. ### Prepare the representation based on an existing report You can prepare a code representation of a report by retrieving the representation of an existing report and making changes based on that representation. 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. To get the representation of an existing report, see [Get the code representation of a report](/docs/get-the-code-representation-of-a-report). ### Prepare the representation using an AI assistant You can prepare a code representation of a report using an AI assistant to compose the representation. Sigma recommends providing the agent with example representations to improve accuracy and performance. Provide an LLM-friendly version of the Sigma documentation and example library, or use an agent skill. To learn more about using the Sigma documentation with AI assistants, see [Add Sigma documentation as context to chat interactions](/docs/use-documentation-mcp-server#add-sigma-documentation-as-context-to-chat-interactions). For examples of report code representations, see the [Report representation example library](/docs/report-representation-example-library). To learn more about skills for AI assistants using Sigma, see [Install skills for AI assistants](/docs/install-skills-for-ai-assistants). ## Identify where to create the report To create a report from a representation, you must identify the folder to create the report in. You can identify a folder and then call the [List files](/reference/list-files) endpoint to retrieve the `id` for the folder: 1. Go to the Sigma **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 **Folders**. The list of your folders appears. If there is no folder for you to create the report in, select **Create folder** to create one. 4. Identify the folder you want to retrieve the `id` for, by name, creator, or other details. 5. Call the [List files](/reference/list-files) endpoint, with a query parameter to filter for folders: #### Get a list of folders request format ```shell curl --request GET \ --url '/v2/files?typeFilters=folder' \ --header 'Authorization: Bearer ' \ --header 'accept:application/json' \ --header 'content-type: application/x-www-form-urlencoded' ``` The response includes a list of folders in your organization, in the following format: #### List folders response format ```json { "entries": [ { "id": "", "urlId": "", "name": "", "type": "folder", "parentId": "", "parentUrlId": "", "permission": "", "path": "", "badge": null, "ownerId": "", "createdBy": "", "updatedBy": "", "createdAt": "", "updatedAt": "", "isArchived": false } ], "total": , "nextPage": null } ``` 6. Using the name or other details you identified in step 4, find the folder you want to retrieve the `id` for, and copy the `id` from the response body. 7. Add the folder `id` to the code representation you prepared earlier as the `folderId`. ## Call the Create a report endpoint Using the access token and code representation you prepared in the previous steps, make a POST request to the [Create a report](/reference/create-report) endpoint using the following format: #### Create a report from a representation request format ```shell curl --request POST \ --url /v2/reports \ --header 'Authorization: Bearer ' \ --header 'content-type: application/yaml' \ --data '' ``` Before creating a report from a code representation, you can call the [Verify a report code representation](/reference/verify-report-spec) endpoint to check if the representation is valid. The endpoint creates the report and returns a response body with the new `reportId`.