Create a report from a code representation (Beta)

You can create a report from a code representation by calling the Create a 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.

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.
• The user associated with your API credentials must be assigned an account type 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.

Prepare a code representation

To create a report using the Create a report endpoint, you must first construct a valid code representation of a report.

You can prepare a representation using any of the following options:

• Prepare the representation manually
• Prepare a representation from multiple YAML documents
• Prepare the representation based on an existing report
• 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.

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.

As an example, the following POST request creates a report with one empty page in a specified folder:

curl --request POST \
    --url <base_url>/v2/reports \
    --header "Authorization: Bearer <access_token>" \
    --header 'content-type:application/json' \
    --data '{"name":"Sample Report","folderId":<folderId>,"contents":{"schemaVersion":1,"kind":"report","elements":[],"pages":[{"id":<pageId>,"name":"Page 1"}],"layout":"<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<Page id=\"<pageId>\"/>\n"}}'

Retrieving that report with includeContents=true returns the representation as follows:

reportId: <reportId>
reportUrlId: <reportUrlId>
createdBy: <userId>
updatedBy: <userId>
createdAt: <timestamp>
updatedAt: <timestamp>
name: Sample Report
url: <reportUrl>
path: <folderPath>
latestVersion: 1
ownerId: <userId>
isArchived: false
documentVersion: 1
contents:
  schemaVersion: 1
  kind: report
  elements: []
  pages:
    - id: <pageId>
      name: Page 1
  config:
    margin: 0
    pageHeight: 1056
    pageWidth: 816
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page id="<pageId>"/>

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.

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 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:

curl --request POST \
    --url <base_url>/v2/reports \
    --header "Authorization: Bearer <access_token>" \
    --header "content-type: application/yaml" \
    --data 'name: Sample Report
folderId: <folderId>
contents:
  schemaVersion: 1
  kind: report
  elements: []
  pages:
    - id: <pageId1>
      name: Page 1
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page id="<pageId1>"/>
    <Page id="<pageId2>"/>
---
contents:
  pages:
    - id: <pageId2>
      name: Page 2'

Retrieving that report with includeContents=true returns the representation as follows:

reportId: <reportId>
reportUrlId: <reportUrlId>
createdBy: <userId>
updatedBy: <userId>
createdAt: <timestamp>
updatedAt: <timestamp>
name: Sample Report
url: <reportUrl>
path: <folderPath>
latestVersion: 1
ownerId: <userId>
isArchived: false
documentVersion: 1
contents:
  schemaVersion: 1
  kind: report
  elements: []
  pages:
    - id: <pageId1>
      name: Page 1
    - id: <pageId2>
      name: Page 2
  config:
    margin: 0
    pageHeight: 1056
    pageWidth: 816
  layout: |
    <?xml version="1.0" encoding="utf-8"?>
    <Page id="<pageId1>"/>
    <Page id="<pageId2>"/>

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.

To get the representation of an existing report, see 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. For examples of report code representations, see the Report representation example library.

To learn more about skills for AI assistants using Sigma, see 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 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 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 endpoint, with a query parameter to filter for folders:

   Get a list of folders request format

   curl --request GET \
       --url '<base_url>/v2/files?typeFilters=folder' \
       --header 'Authorization: Bearer <access_token>' \
       --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

   {
       "entries": [
           {
               "id": "<folder_id>",
               "urlId": "<folder_url_id>",
               "name": "<folder_name>",
               "type": "folder",
               "parentId": "<parent_folder_id>",
               "parentUrlId": "<parent_folder_url_id>",
               "permission": "<permission_level>",
               "path": "<folder_path>",
               "badge": null,
               "ownerId": "<owner_user_id>",
               "createdBy": "<creator_user_id>",
               "updatedBy": "<updater_user_id>",
               "createdAt": "<creation_timestamp>",
               "updatedAt": "<update_timestamp>",
               "isArchived": false
           }
       ],
       "total": <total_number_of_folders>,
       "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 endpoint using the following format:

curl --request POST \
    --url <base_url>/v2/reports \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type: application/yaml' \
    --data '<representation>'

The endpoint creates the report and returns a response body with the new reportId.