Create a data model from a code representation

You can create a data model from a code representation by calling the Create a data model from a code representation endpoint with the code representation in the request body.

This document provides step-by-step instructions for using this endpoint to create a data model from a code representation. For more information on working with data models programmatically, see Manage data models as code.

System and user requirements

The ability to create data models 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 the Admin account type.

Generate API client credentials and an API access token

Prepare the representation

To create a data model from a representation, you must first construct a valid code representation of a data model. For more information on the structure of a data model representation, see Manage data models as code. For example representations with various features and configurations, see the Example library.

A valid code representation of a data model for a POST request requires the following fields:

• name: The name of the data model.
• folderId: The ID of the folder to create the data model in.
• schemaVersion: The version of the representation schema to use.
• pages: An array of page objects and their contents.
  • id: An ID for the page. Overwritten upon creation.
  • name: The name of the page.
  • elements: An array of element objects and their contents. Can be empty.

As an example, the following POST request creates an empty data model in a specified folder:

curl --request POST \
    --url <base_url>/v2/dataModels/spec \
    --header 'Authorization: Bearer <access_token>' \
    --header 'content-type:application/json' \
    --data '{"name":"Sample Data Model","schemaVersion":1,"folderId":"<folder_id>","pages":[{"id":"","name":"Page 1","elements":[]}]}'

And the JSON representation for the data model created by that request appears as follows:

{
    "name": "Sample Data Model",
    "schemaVersion": 1,
    "folderId": "<folder_id>",
    "pages": [
        {
            "id": "",
            "name": "Page 1",
            "elements": []
        }
    ]
}

💡

In this example, the id key in the pages array is left blank. This is valid in this example because Sigma generates an ID for the page when the data model is created, and the request only creates a single page. For more complex POST requests with several pages and elements, Sigma requires you to include unique IDs for pages so that elements can reference them within the same request body.

For more examples of code representations for specific data model configurations, see the Example library. Alternatively, you can retrieve the code representation of an existing data model by calling the Get the code representation of a data model endpoint with the dataModelId for the data model.

Identify the folder to create the data model in

To create a data model from a representation, you must identify the folder to create the data model 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 My 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 data model in, you can create a new folder by selecting Create folder.

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

   Shell

   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:

{
    "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 data model from a representation endpoint

Using the access token and code representation you prepared in the previous steps, make a POST request to the Create a data model from a code representation endpoint using the following format:

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

The data model is created and the response body contains the dataModelId for the new data model.